Skip to content

Clarify importance of .crt extension in customCAs

Mitchell Nielsen requested to merge update-custom-ca-docs into master

What does this MR do?

Clarifies the importance of the '.crt' extension in customCA keys,
as those keys are used as the filename. The filename is important
now that the Certificates image is Debian-based, where the
'update-ca-certificates' utility requires files in
/usr/local/share/ca-certificates to include the '.crt' extension
to be considered. The Alpine 'update-ca-certificates' utility
does not have this requirement, although the
[documentation](https://gitlab.alpinelinux.org/alpine/ca-certificates/-/blob/master/update-ca-certificates.8)
claims that it does.

This addresses issues such as
https://gitlab.com/gitlab-org/cloud-native/gitlab-operator/-/issues/1088,
where upgrading to version 6.9.0 or greater of the Helm Charts (where
alpine-certificates was replaced with certificates) would cause the
customCAs to not be present in the Pods as expected.

Related issues

Closes gitlab-org/cloud-native/gitlab-operator#1088 (closed)

Testing

Confirming that Debian will skip files without '.crt'

$ docker run --rm -it registry.gitlab.com/gitlab-org/build/cng/certificates:v15.9.0 bash
Begin parsing .tpl templates from /etc
root@f2180f4a9811:/# touch /usr/local/share/ca-certificates/test
root@f2180f4a9811:/# update-ca-certificates
Updating certificates in /etc/ssl/certs...
0 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.
root@f2180f4a9811:/#
root@f2180f4a9811:/#
root@f2180f4a9811:/# touch /usr/local/share/ca-certificates/test.crt
root@f2180f4a9811:/# update-ca-certificates
Updating certificates in /etc/ssl/certs...
rehash: warning: skipping test.pem,it does not contain exactly one certificate or CRL
1 added, 0 removed; done.
Running hooks in /etc/ca-certificates/update.d...
done.

Confirming that Alpine will auto-append the file extension

$ docker run --rm -it alpine:latest /bin/sh
/ # apk update && apk add ca-certificates
fetch https://dl-cdn.alpinelinux.org/alpine/v3.17/main/x86_64/APKINDEX.tar.gz
fetch https://dl-cdn.alpinelinux.org/alpine/v3.17/community/x86_64/APKINDEX.tar.gz
v3.17.2-140-gb8e2be09535 [https://dl-cdn.alpinelinux.org/alpine/v3.17/main]
v3.17.2-147-g556d527d792 [https://dl-cdn.alpinelinux.org/alpine/v3.17/community]
OK: 17811 distinct packages available
(1/1) Installing ca-certificates (20220614-r4)
Executing busybox-1.35.0-r29.trigger
Executing ca-certificates-20220614-r4.trigger
OK: 8 MiB in 16 packages
/ # vi /usr/local/share/ca-certificates/test # paste content of a sample CA file
/ # update-ca-certificates
/ # ls -l /etc/ssl/certs/ | grep test
lrwxrwxrwx    1 root     root            37 Mar  6 23:12 ca-cert-test.pem -> /usr/local/share/ca-certificates/test
lrwxrwxrwx    1 root     root            16 Mar  6 23:12 cee1e53c.0 -> ca-cert-test.pem
/ # less /etc/ssl/certs/ca-certificates.crt # grep for your sample CA file, should be at the end

Confirming that UBI8 does not have this problem

$ docker run --rm -it -u 0 registry.gitlab.com/gitlab-org/build/cng/certificates:v15.9.0-ubi8 bash
bash-4.4# cd /usr/share/pki/ca-trust-source/anchors/
bash-4.4# vi test # paste in an example CA here
bash-4.4# update-ca-trust
bash-4.4# less /etc/pki/ca-trust/extracted/pem/tls-ca-bundle.pem # search for the example CA you pasted earlier

Checklist

See Definition of done.

For anything in this list which will not be completed, please provide a reason in the MR discussion.

Required

  • Merge Request Title and Description are up to date, accurate, and descriptive
  • MR targeting the appropriate branch
  • MR has a green pipeline on GitLab.com
  • When ready for review, MR is labeled "~workflow::ready for review" per the Distribution MR workflow

Expected (please provide an explanation if not completing)

  • Test plan indicating conditions for success has been posted and passes
  • Documentation created/updated
  • Tests added
  • Integration tests added to GitLab QA
  • Equivalent MR/issue for omnibus-gitlab opened
  • Validate potential values for new configuration settings. Formats such as integer 10, duration 10s, URI scheme://user:passwd@host:port may require quotation or other special handling when rendered in a template and written to a configuration file.
Edited by Mitchell Nielsen

Merge request reports