Document custom CA certificates for AI Gateway Helm deployments

Hamza Hassanainrequested to merge
gitlab-community/gitlab-org/gitlab:606979-aigw-custom-ca-docs into master

What does this MR do?

The old steps for adding a custom root CA to the AI Gateway didn't work. The CA never reached the bundle the AI Gateway reads. I rewrote the "Add the root CA certificate to the AI Gateway container's CA bundle" section. It now has separate steps for the GitLab Helm chart, the stand-alone AI Gateway chart, and Docker. The H3 heading is the same, so existing links still work.

For the GitLab Helm chart, the page now uses global.certificates.customCAs, which adds the CA to the container's system bundle. The AI Gateway uses Certifi by default, so the steps also point REQUESTS_CA_BUNDLE and SSL_CERT_FILE to that bundle. This needs GitLab chart 10.1 or later. Older charts bundle an AI Gateway chart that ignores customCAs.

The issue says customCAs also works for a stand-alone AI Gateway chart. I don't think it does. In the stand-alone chart, the certificate templates are empty placeholders (source). Only the GitLab chart fills them in (source). So for the stand-alone chart, I kept the "mount your own bundle" approach and fixed it.

The old stand-alone steps had these problems:

  • The CA was appended to the local bundle, and then kubectl cp overwrote that file.
  • The kubectl cp command had a stray trailing dot and used the wrong namespace.
  • The environment variables pointed to a file that didn't exist, because the secret key had a different name.
  • The note about "later versions of the chart" was misleading, because the bundle comes from the image. The page now says to repeat the steps after an image upgrade.

I also moved the mount path from /tmp to /etc/ai-gateway/certs. A secret volume replaces the whole directory. Mounted on /tmp, it leaves a read-only /tmp with only the bundle in it. The stand-alone steps now copy the bundle with kubectl exec and cat, so the container does not need tar. The Docker steps copy the bundle out of the image with docker run. The FIPS-validated image is based on UBI 9, so for it both steps copy /etc/pki/tls/certs/ca-bundle.crt instead.

I used H4 subsections instead of tabs, to match the existing Docker subsection. I can switch to tabs if you prefer.

@jpcyiza Hello! Since you wrote the chart, can you please check these two points?

  1. Is it right that customCAs has no effect when the AI Gateway chart is deployed on its own?
  2. Under the GitLab chart, are REQUESTS_CA_BUNDLE and SSL_CERT_FILE the right way to use the system bundle? Or is there a chart setting for it? If they aren't needed, I can drop them.

I re-ran these checks against the current branch:

$ git diff --check upstream/master...origin/606979-aigw-custom-ca-docs
$ git diff -U0 upstream/master...origin/606979-aigw-custom-ca-docs | grep '^+[^+]' | awk 'length($0)-1>100' | wc -l
2
$ git grep -n 'add-the-root-ca-certificate-to-the-ai-gateway' origin/606979-aigw-custom-ca-docs -- doc

The 2 long lines are a sentence with a long URL and the kubectl exec command. The empty git grep means no other page links to this section.

I checked the steps against the chart and image source. The rest runs in the pipeline.

Related issues

Closes #606979 (closed)

Author's checklist

If you are a GitLab team member and only adding documentation, do not add any of the following labels:

  • ~"frontend"
  • ~"backend"
  • ~"type::bug"
  • ~"database"

These labels cause the MR to be added to code verification QA issues.

Reviewer's checklist

Documentation-related MRs should be reviewed by a Technical Writer for a non-blocking review, based on Documentation Guidelines and the Style Guide.

If you aren't sure which tech writer to ask, use roulette or ask in the #docs Slack channel.

  • If the content requires it, ensure the information is reviewed by a subject matter expert.
  • Technical writer review items:
    • Ensure docs metadata is present and up-to-date.
    • Ensure the appropriate labels are added to this MR.
    • Ensure a release milestone is set.
    • If relevant to this MR, ensure content topic type principles are in use, including:
      • The headings should be something you'd do a Google search for. Instead of Default behavior, say something like Default behavior when you close an issue.
      • The headings (other than the page title) should be active. Instead of Configuring GDK, say something like Configure GDK.
      • Any task steps should be written as a numbered list.
      • If the content still needs to be edited for topic types, you can create a follow-up issue with the docs-technical-debt label.
  • Review by assigned maintainer, who can always request/require the reviews above. Maintainer's review can occur before or after a technical writer review.

Implemented with AI assistance; I reviewed and tested the changes.

Edited by Hamza Hassanain

Merge request reports