From 48df67696b4e4bf4a3da70f06320cff8fcb0d97a Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Mon, 18 Nov 2024 10:02:51 +0000 Subject: [PATCH] ammending syntax comments & added extra documentation on logic flow --- .../using-authenticated-private-registries.md | 29 ++++++++++--------- 1 file changed, 16 insertions(+), 13 deletions(-) diff --git a/content/en/docs/porch/using-porch/using-authenticated-private-registries.md b/content/en/docs/porch/using-porch/using-authenticated-private-registries.md index 4180949f..4536c5b8 100644 --- a/content/en/docs/porch/using-porch/using-authenticated-private-registries.md +++ b/content/en/docs/porch/using-porch/using-authenticated-private-registries.md @@ -8,15 +8,17 @@ description: "" To enable the Porch function runner to pull kpt function images from authenticated private registries, the system requires: {{% alert title="Note" color="primary" %}} -Please note sections 4, 5 and 6 are only required if your private registries are set up to use TLS with either self signed or custom/local CA's +Please note items 4, 5 and 6 are only required if your private registries are set up to use TLS with custom/local certificate authorities (CAs) or self-signed certificates (Not recommended for security). {{% /alert %}} 1. Creating a Kubernetes secret using a JSON file according to the Docker config schema, containing valid credentials for each authenticated registry. 2. Mounting this new secret as a volume on the function runner. -3. Enabling the external registries feature, providing the path and name of the mounted secret to the function runner using the arguments *--enable-private-registry*, *--registry-auth-secret-path* and *--registry-auth-secret-name* respectively. -4. Creating a Kubernetes secret using the TLS information for the registry you wish to use. +3. Configuring private registry functionality in the function runner's arguments: + 1. Enabling the functionality using the argument *--enable-private-registry*. + 2. Providing the path and name of the mounted secret using the arguments *--registry-auth-secret-path* and *--registry-auth-secret-name* respectively. +4. Creating a Kubernetes secret using TLS information valid for all registries you wish to use. 5. Mounting the secret containing the registries TLS information to the function runner similarly to step 2. -6. Enabling the TLS feature and providing the path of the mounted secret to the function runner using the arguments *--enable-private-registry* and *--tls-secret-path* respectively. +6. Enabling TLS functionality and providing the path of the mounted secret to the function runner using the arguments *--enable-tls-registry* and *--tls-secret-path* respectively. An example template of what a docker *config.json* file looks like is as follows below. The base64 encoded value *bXlfdXNlcm5hbWU6bXlfcGFzc3dvcmQ=* of the *auth* key decodes to *my_username:my_password*, which is the format used by the config when authenticating. @@ -66,17 +68,15 @@ metadata: name: namespace: porch-system data: - ca.crt: base64_encoded_ca.crt_data - tls.crt: base64_encoded_tls.crt_data - tls.key: base64_encoded_tls.key_data + : type: kubernetes.io/tls ``` {{% alert title="Note" color="primary" %}} -The function runner will look specifically for a *ca.crt* or *ca.pem* file for TLS transport and so the ca TLS data must use that key/file naming. +The content in ** must be in PEM (Privacy Enhanced Mail) format and the ** must be named *ca.crt* or *ca.pem* no other values are accepted. {{% /alert %}} -Next you must mount the secrets as a volume on the function runner deployment. Add the following snippet to the Deployment object in the *2-function-runner.yaml* file noting that the last entries in the `volumes` and `volumeMounts` fields are only required for TLS private registries: +Next you must mount the secrets as volumes on the function runner deployment. Add the following snippet to the Deployment object in the *2-function-runner.yaml* file (Note that the `tls-registry-config` entries in the `volumes` and `volumeMounts` fields are only required for TLS-secured private registries): ```yaml volumeMounts: @@ -100,13 +100,13 @@ volumes: secretName: ``` -You may specify your desired `mountPath:` so long as the function runner can access it. +You may specify your desired paths for each `mountPath:` so long as the function runner can access them. {{% alert title="Note" color="primary" %}} The chosen `mountPath:` should use its own, dedicated sub-directory, so that it does not overwrite access permissions of the existing directory. For example, if you wish to mount on `/var/tmp` you should use `mountPath: /var/tmp/` etc. {{% /alert %}} -The *--enable-tls-registry* and *--tls-secret-path* variables are only required if the user has a private TLS registry. they are used to indicate to the function runner that it should try and authenticate to the registry with TLS transport and should use the TLS certificate information found on the path provided in *--tls-secret-path*. +he *--enable-tls-registry* and *--tls-secret-path* variables are only required if a private registry has TLS enabled. They indicate to the function runner that it should attempt authentication to the registry using TLS, and should use the TLS certificate information found on the path provided in *--tls-secret-path*. Lastly you must enable private registry functionality along with providing the path and name of the secret. Add the `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: @@ -125,10 +125,13 @@ command: The `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments have default values of *false*, */var/tmp/auth-secret/.dockerconfigjson* and *auth-secret* respectively; however, these should be overridden to enable the functionality and match user specifications. -The *--enable-tls-registry* and *--tls-secret-path* arguments have default values of *false* and */var/tmp/tls-secret/* respectively; however these should be configured by the user and are only necessary when the user has a private TLS registry. +The *--enable-tls-registry* and *--tls-secret-path* arguments have default values of *false* and */var/tmp/tls-secret/* respectively; however, these should be configured by the user and are only necessary when using a private registry secured with TLS. + +It is important to note that enabling TLS registry functionality makes the function runner attempt connection to the registry provided in the porch file using the mounted tls certificate. if this certificate is invalid for the provided registry it will attempt again but with the Intermediate Certificates stored on the machine for use in TLS with "well-known websites" e.g. Github. If this also fails then it will attempt without TLS as a last resort which if also failed will error out letting the user know the error. {{% alert title="Note" color="primary" %}} -It is vital that the user has configured the node which the function runner is operating on with the certificate information which is used in the **. If this is not configured correctly even if the certificate is correct the function runner will be able to pull the image but the krm function pod spun up to run the function will error out with a *x509 certificate signed by unknown authority*. +It is vital that the user has pre-configured the Kubernetes node which the function runner is operating on with the same TLS certificate information as is used in the ** secret. If this is not configured correctly, then even if the certificate is correctly configured in the function runner, the kpt function will not run - the function runner will be able to pull the image, but the KRM function pod created to run the function will fail with the error *x509 certificate signed by unknown authority*. +This pre-configuration setup is heavily cluster/implementation-dependent - consult your cluster's specific documentation about adding self-signed certificates or private/internal CA certs to your cluster. {{% /alert %}} With this last step, if your Porch package uses a custom kpt function image stored in an authenticated private registry (for example `- image: ghcr.io/private-registry/set-namespace:customv2`), the function runner will now use the secret info to replicate your secret on the `porch-fn-system` namespace and specify it as an `imagePullSecret` for the function pods, as documented [here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/).