From 129fc0c119bb5724f6883e8f369a4597bcc4725c Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Wed, 13 Nov 2024 10:16:54 +0000 Subject: [PATCH 01/26] adding documentation for tls registries configuration --- .../using-authenticated-private-registries.md | 46 ++++++++++++++++++- 1 file changed, 44 insertions(+), 2 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 c0b7257e..855e7381 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 @@ -7,9 +7,16 @@ 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 +{{% /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. Providing the path of the mounted secret to the function runner using the argument `--registry-auth-secret-path` +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. +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 funtion runner using the arguments `--enable-private-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. @@ -50,7 +57,26 @@ metadata: type: kubernetes.io/dockerconfigjson ``` -Next you must mount the secret as a volume on the function runner deployment. Add the following snippet to the Deployment object in the *2-function-runner.yaml* file: +A typical secret containing TLS information will take on the a similar format to the following: + +```yaml +apiVersion: v1 +kind: Secret +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. +{{% /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: ```yaml volumeMounts: @@ -59,6 +85,9 @@ Next you must mount the secret as a volume on the function runner deployment. Ad - mountPath: /var/tmp/auth-secret name: docker-config readOnly: true + - mountPath: /var/tmp/tls-secret/ + name: tls-registry-config + readOnly: true volumes: - name: pod-cache-config-volume configMap: @@ -66,6 +95,9 @@ volumes: - name: docker-config secret: secretName: + - name: tls-registry-config + secret: + secretName: ``` You may specify your desired `mountPath:` so long as the function runner can access it. @@ -74,6 +106,8 @@ You may specify your desired `mountPath:` so long as the function runner can acc 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 autenticate to the registry with TLS transport 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: ```yaml @@ -83,10 +117,18 @@ command: - --enable-private-registry=true - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson - --registry-auth-secret-name= + - --enable-tls-registry=true + - --tls-secret-path=/var/tmp/tls-secret/ - --functions=/functions - --pod-namespace=porch-fn-system ``` 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. + +{{% 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*. +{{% /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/). From b620d7defa2a407c2c2582c529b4f2a532ddcd08 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:19:11 +0000 Subject: [PATCH 02/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 855e7381..02c999d2 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 @@ -14,7 +14,7 @@ Please note sections 4, 5 and 6 are only required if your private registries are 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. +4. Creating a Kubernetes secret using the TLS information for the registry 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 funtion runner using the arguments `--enable-private-registry` and `--tls-secret-path` respectively. From c7068b9ec3d7fd39c187ee32c09ecaebe8abdc1d Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:19:39 +0000 Subject: [PATCH 03/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari From e823320ea56f8b43a67ac0e4a755435dc7aeb75e Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:20:04 +0000 Subject: [PATCH 04/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 02c999d2..88d8ad02 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 @@ -11,7 +11,7 @@ To enable the Porch function runner to pull kpt function images from authenticat 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 {{% /alert %}} -1. Creating a kubernetes secret using a JSON file according to the Docker config schema, containing valid credentials for each authenticated registry. +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. From b187beb14c22bed15c64c8b7223ebc1872d1c51a Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:20:18 +0000 Subject: [PATCH 05/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 88d8ad02..7b3274ac 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 @@ -13,7 +13,7 @@ Please note sections 4, 5 and 6 are only required if your private registries are 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. +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. 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 funtion runner using the arguments `--enable-private-registry` and `--tls-secret-path` respectively. From cb93ae4521dd84b36e6478a22db94a83be091381 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:20:27 +0000 Subject: [PATCH 06/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 7b3274ac..da172ce4 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 @@ -16,7 +16,7 @@ Please note sections 4, 5 and 6 are only required if your private registries are 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. 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 funtion runner using the arguments `--enable-private-registry` and `--tls-secret-path` respectively. +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. 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. From 37d71f94638e008379bf10898b26ea4dc45edfaa Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:20:34 +0000 Subject: [PATCH 07/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 da172ce4..7c42bea1 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 @@ -106,7 +106,7 @@ You may specify your desired `mountPath:` so long as the function runner can acc 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 autenticate to the registry with TLS transport and should use the TLS certificate information found on the path provided in `--tls-secret-path`. +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*. 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: From f911b95a6016fac9b42b6c71ec8d86270372ef5c Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:20:45 +0000 Subject: [PATCH 08/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 7c42bea1..cecb1b55 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 @@ -125,7 +125,7 @@ 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 the user has a private TLS registry. {{% 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*. From 90b38c38b7c6889f74829a2869d93b77ba8b6bc0 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 13 Nov 2024 16:20:59 +0000 Subject: [PATCH 09/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Gergely Csatari --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 cecb1b55..4180949f 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 @@ -128,7 +128,7 @@ The `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-a 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. {{% 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 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*. {{% /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/). From 48df67696b4e4bf4a3da70f06320cff8fcb0d97a Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Mon, 18 Nov 2024 10:02:51 +0000 Subject: [PATCH 10/26] 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/). From 249fa690d5157b011485e940ba848edd8820055c Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Mon, 18 Nov 2024 12:19:38 +0000 Subject: [PATCH 11/26] added correct apostrophe --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 4536c5b8..1c9c241e 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 @@ -17,7 +17,7 @@ Please note items 4, 5 and 6 are only required if your private registries are se 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. +5. Mounting the secret containing the registries' TLS information to the function runner similarly to step 2. 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. From b779bed4f5e10710748572d9308cbb8c57341524 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Mon, 18 Nov 2024 14:04:57 +0000 Subject: [PATCH 12/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: JamesMcDermott --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 1c9c241e..fd65747e 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 @@ -73,7 +73,7 @@ type: kubernetes.io/tls ``` {{% alert title="Note" color="primary" %}} -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. +The content in ** must be in PEM (Privacy Enhanced Mail) format, and the ** must be *ca.crt* or *ca.pem*. No other values are accepted. {{% /alert %}} 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): From 57c1c4bc9f2c1f103b92f86c3ca4df4953111384 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Mon, 18 Nov 2024 14:05:03 +0000 Subject: [PATCH 13/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: JamesMcDermott --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 fd65747e..bd097a5f 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 @@ -106,7 +106,7 @@ You may specify your desired paths for each `mountPath:` so long as the function 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 %}} -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*. +The *--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: From 401ebffd8ef460a14fd0a74c56d5ce5d4bd5622d Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Mon, 18 Nov 2024 14:05:15 +0000 Subject: [PATCH 14/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: JamesMcDermott --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 bd097a5f..347cad2a 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 @@ -127,7 +127,7 @@ The `--enable-private-registry`, `--registry-auth-secret-path` and `--registry-a 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. +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 try again using the Intermediate Certificates stored on the machine for use in TLS with "well-known websites" (e.g. GitHub). If this also fails, it will attempt to connect without TLS: if this last resort fails, it will return an error to the user. {{% alert title="Note" color="primary" %}} 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*. From 4f27def85a76b94e61633f47290ad36d4ebdd968 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Mon, 18 Nov 2024 15:45:52 +0000 Subject: [PATCH 15/26] changed argument name and description to clarify logic --- .../using-porch/using-authenticated-private-registries.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 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 347cad2a..14bacfd1 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 @@ -18,7 +18,7 @@ Please note items 4, 5 and 6 are only required if your private registries are se 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 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. +6. Enabling TLS functionality and providing the path of the mounted secret to the function runner using the arguments *--enable-private-registry-tls* 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. @@ -106,7 +106,7 @@ You may specify your desired paths for each `mountPath:` so long as the function 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 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*. +TThe *--enable-private-registry-tls* 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: @@ -117,7 +117,7 @@ command: - --enable-private-registry=true - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson - --registry-auth-secret-name= - - --enable-tls-registry=true + - --enable-private-registry-tls=true - --tls-secret-path=/var/tmp/tls-secret/ - --functions=/functions - --pod-namespace=porch-fn-system @@ -125,7 +125,7 @@ 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 using a private registry secured with TLS. +The *--enable-private-registry-tls* 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 try again using the Intermediate Certificates stored on the machine for use in TLS with "well-known websites" (e.g. GitHub). If this also fails, it will attempt to connect without TLS: if this last resort fails, it will return an error to the user. From 387d6959e0761124becb35f71728809313783bef Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Mon, 18 Nov 2024 15:46:48 +0000 Subject: [PATCH 16/26] removed typo --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 14bacfd1..e331eca4 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 @@ -106,7 +106,7 @@ You may specify your desired paths for each `mountPath:` so long as the function 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 %}} -TThe *--enable-private-registry-tls* 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*. +The *--enable-private-registry-tls* 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: From bdac5ba5196feb144e6fd148d2238f1419b333dd Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Mon, 18 Nov 2024 16:01:50 +0000 Subject: [PATCH 17/26] more argument renames for clarity --- .../using-authenticated-private-registries.md | 16 ++++++++-------- 1 file changed, 8 insertions(+), 8 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 e331eca4..9b13fa9d 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 @@ -14,11 +14,11 @@ Please note items 4, 5 and 6 are only required if your private registries are se 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. Configuring private registry functionality in the function runner's arguments: - 1. Enabling the functionality using the argument *--enable-private-registry*. + 1. Enabling the functionality using the argument *--enable-private-registries*. 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 TLS functionality and providing the path of the mounted secret to the function runner using the arguments *--enable-private-registry-tls* 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-private-registries-tls* 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. @@ -106,26 +106,26 @@ You may specify your desired paths for each `mountPath:` so long as the function 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-private-registry-tls* 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*. +The *--enable-private-registries-tls* 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: +Lastly you must enable private registry functionality along with providing the path and name of the secret. Add the `--enable-private-registries`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: ```yaml command: - /server - --config=/config.yaml - - --enable-private-registry=true + - --enable-private-registries=true - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson - --registry-auth-secret-name= - - --enable-private-registry-tls=true + - --enable-private-registries-tls=true - --tls-secret-path=/var/tmp/tls-secret/ - --functions=/functions - --pod-namespace=porch-fn-system ``` -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-private-registries`, `--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-private-registry-tls* 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. +The *--enable-private-registries-tls* 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 try again using the Intermediate Certificates stored on the machine for use in TLS with "well-known websites" (e.g. GitHub). If this also fails, it will attempt to connect without TLS: if this last resort fails, it will return an error to the user. From b0ed148db824b0e75ba0c3f28bede384c5875f11 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Tue, 19 Nov 2024 17:23:08 +0000 Subject: [PATCH 18/26] restructured function-runner private registries documentation for clarity --- .../using-authenticated-private-registries.md | 98 ++++++++++++------- 1 file changed, 63 insertions(+), 35 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 9b13fa9d..0b3977bc 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 @@ -5,20 +5,26 @@ weight: 4 description: "" --- -To enable the Porch function runner to pull kpt function images from authenticated private registries, the system requires: +The sections below will describe the different configuration options of the function runner pertaining to the image storage location of the kpt functions used by the function runner when rendering of the porch package occurs. {{% alert title="Note" color="primary" %}} -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). +Please note the function runner is setup to run by default with a public container registry such as [GCR](https://gcr.io/kpt-fn/). No further configuration is required if that is the intended use case. +However if a more customized setup is required please see the below configuration options {{% /alert %}} +## Configuring function runner to operate with private container registries + +If you wish to have a private container registry to store your kpt functions either online e.g. (Github's GHCR) or locally e.g. (Harbor or Jfrog) requiring authentication (username/password or token) then see below. + +To enable the Porch function runner to pull kpt function images from authenticated private registries, the system requires: + 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. Configuring private registry functionality in the function runner's arguments: 1. Enabling the functionality using the argument *--enable-private-registries*. 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 TLS functionality and providing the path of the mounted secret to the function runner using the arguments *--enable-private-registries-tls* and *--tls-secret-path* respectively. + +### Kubernetes secret setup for private registry using docker config 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. @@ -59,6 +65,52 @@ metadata: type: kubernetes.io/dockerconfigjson ``` +### Mounting docker config secret to the function runner + +Next you must mount the secret as a volume on the function runner deployment. Add the following sections to the Deployment object in the *2-function-runner.yaml* file: + +```yaml + volumeMounts: + - mountPath: /var/tmp/auth-secret + name: docker-config + readOnly: true +volumes: + - name: docker-config + secret: + secretName: +``` + +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 %}} + +### Configuring function runner environment variables for private registries + +Lastly you must enable private registry functionality along with providing the path and name of the secret. Add the `--enable-private-registries`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: + +```yaml +command: + - --enable-private-registries=true + - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson + - --registry-auth-secret-name= +``` + +The `--enable-private-registries`, `--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. + +With this last step, if your Porch package uses kpt function images stored in an 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/). + +## Configuring function runner to use custom TLS for private container registries + +If your private container registry uses a custom certificate for TLS authentication then extra configuration is required for the function runner to integrate with. See below + +1. Creating a Kubernetes secret using TLS information valid for all private registries you wish to use. +2. Mounting the secret containing the registries' TLS information to the function runner similarly to step 2. +3. Enabling TLS functionality and providing the path of the mounted secret to the function runner using the arguments *--enable-private-registries-tls* and *--tls-secret-path* respectively. + +### Kubernetes secret layout for TLS certificate + A typical secret containing TLS information will take on the a similar format to the following: ```yaml @@ -76,62 +128,38 @@ type: kubernetes.io/tls The content in ** must be in PEM (Privacy Enhanced Mail) format, and the ** must be *ca.crt* or *ca.pem*. No other values are accepted. {{% /alert %}} -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): +### Mounting TLS certificate secret to the function runner + +The TLS secret must then be mounted onto the function runner similarly to how the docker config secret was done previously [here](#mounting-docker-config-secret-to-the-function-runner). ```yaml volumeMounts: - - mountPath: /pod-cache-config - name: pod-cache-config-volume - - mountPath: /var/tmp/auth-secret - name: docker-config - readOnly: true - mountPath: /var/tmp/tls-secret/ name: tls-registry-config readOnly: true volumes: - - name: pod-cache-config-volume - configMap: - name: pod-cache-config - - name: docker-config - secret: - secretName: - name: tls-registry-config secret: secretName: ``` -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 %}} +### Configuring function runner environment variables for TLS on private registries The *--enable-private-registries-tls* 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-registries`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: - ```yaml command: - - /server - - --config=/config.yaml - - --enable-private-registries=true - - --registry-auth-secret-path=/var/tmp/auth-secret/.dockerconfigjson - - --registry-auth-secret-name= - --enable-private-registries-tls=true - --tls-secret-path=/var/tmp/tls-secret/ - - --functions=/functions - - --pod-namespace=porch-fn-system ``` -The `--enable-private-registries`, `--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-private-registries-tls* 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. +### Function runner logic flow when TLS registries are enabled + 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 try again using the Intermediate Certificates stored on the machine for use in TLS with "well-known websites" (e.g. GitHub). If this also fails, it will attempt to connect without TLS: if this last resort fails, it will return an error to the user. {{% alert title="Note" color="primary" %}} 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/). From a762acff1e48601a1fe66d273cfdf6d56c401c23 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Tue, 19 Nov 2024 17:24:21 +0000 Subject: [PATCH 19/26] changed title to clarify which porch component its based on --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 0b3977bc..fabfd37f 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 @@ -1,5 +1,5 @@ --- -title: "Using authenticated private registries" +title: "Using authenticated private registries with the Porch function runner" type: docs weight: 4 description: "" From 0f917161883e090eefe5194e9f40faf1662b3c73 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 20 Nov 2024 14:00:24 +0000 Subject: [PATCH 20/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 fabfd37f..f9af0ea0 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 @@ -5,7 +5,7 @@ weight: 4 description: "" --- -The sections below will describe the different configuration options of the function runner pertaining to the image storage location of the kpt functions used by the function runner when rendering of the porch package occurs. +The Porch function runner pulls kpt function images from registries and uses them for rendering kpt packages in Porch. The function runner is set up by default to fetch kpt function images from public container registries such as [GCR](https://gcr.io/kpt-fn/) and the configuration options described here are not required for such public registries. {{% alert title="Note" color="primary" %}} Please note the function runner is setup to run by default with a public container registry such as [GCR](https://gcr.io/kpt-fn/). No further configuration is required if that is the intended use case. From c8d56d3f6860bb7426c56813529cb4a358403ac2 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 20 Nov 2024 14:00:52 +0000 Subject: [PATCH 21/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> --- .../porch/using-porch/using-authenticated-private-registries.md | 1 - 1 file changed, 1 deletion(-) 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 f9af0ea0..507f8e1f 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,7 +8,6 @@ description: "" The Porch function runner pulls kpt function images from registries and uses them for rendering kpt packages in Porch. The function runner is set up by default to fetch kpt function images from public container registries such as [GCR](https://gcr.io/kpt-fn/) and the configuration options described here are not required for such public registries. {{% alert title="Note" color="primary" %}} -Please note the function runner is setup to run by default with a public container registry such as [GCR](https://gcr.io/kpt-fn/). No further configuration is required if that is the intended use case. However if a more customized setup is required please see the below configuration options {{% /alert %}} From 5d4a5bf1654b6e1117d2c6e4cf805f44c821d51f Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 20 Nov 2024 14:01:02 +0000 Subject: [PATCH 22/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> --- .../porch/using-porch/using-authenticated-private-registries.md | 1 - 1 file changed, 1 deletion(-) 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 507f8e1f..0e2faf33 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,7 +8,6 @@ description: "" The Porch function runner pulls kpt function images from registries and uses them for rendering kpt packages in Porch. The function runner is set up by default to fetch kpt function images from public container registries such as [GCR](https://gcr.io/kpt-fn/) and the configuration options described here are not required for such public registries. {{% alert title="Note" color="primary" %}} -However if a more customized setup is required please see the below configuration options {{% /alert %}} ## Configuring function runner to operate with private container registries From fc54bbba0a4750c3087d7d140b8520fedcca0ec3 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 20 Nov 2024 14:01:12 +0000 Subject: [PATCH 23/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 0e2faf33..3be8c283 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 @@ -12,7 +12,7 @@ The Porch function runner pulls kpt function images from registries and uses the ## Configuring function runner to operate with private container registries -If you wish to have a private container registry to store your kpt functions either online e.g. (Github's GHCR) or locally e.g. (Harbor or Jfrog) requiring authentication (username/password or token) then see below. +This section describes how set up authentication for a private container registry containing kpt functions online e.g. (Github's GHCR) or locally e.g. (Harbor or Jfrog) that require authentication (username/password or token). To enable the Porch function runner to pull kpt function images from authenticated private registries, the system requires: From 06f7dc7b0944dc4445c61745d19397c96c3c60c2 Mon Sep 17 00:00:00 2001 From: Catalin Stratulat <159934629+Catalin-Stratulat-Ericsson@users.noreply.github.com> Date: Wed, 20 Nov 2024 14:01:22 +0000 Subject: [PATCH 24/26] Update content/en/docs/porch/using-porch/using-authenticated-private-registries.md Co-authored-by: Liam Fallon <35595825+liamfallon@users.noreply.github.com> --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 3be8c283..28528d8a 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 @@ -14,7 +14,7 @@ The Porch function runner pulls kpt function images from registries and uses the This section describes how set up authentication for a private container registry containing kpt functions online e.g. (Github's GHCR) or locally e.g. (Harbor or Jfrog) that require authentication (username/password or token). -To enable the Porch function runner to pull kpt function images from authenticated private registries, the system requires: +To enable pulling of kpt function images from authenticated private registries by the Porch function runner the system requires: 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. From 3fd0e3412e2747714097de8ec74617208faae7cb Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Wed, 20 Nov 2024 14:10:17 +0000 Subject: [PATCH 25/26] removed unnecessary note section + added numbering to sections --- .../using-authenticated-private-registries.md | 19 ++++++++----------- 1 file changed, 8 insertions(+), 11 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 28528d8a..07d98f4f 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 @@ -7,10 +7,7 @@ description: "" The Porch function runner pulls kpt function images from registries and uses them for rendering kpt packages in Porch. The function runner is set up by default to fetch kpt function images from public container registries such as [GCR](https://gcr.io/kpt-fn/) and the configuration options described here are not required for such public registries. -{{% alert title="Note" color="primary" %}} -{{% /alert %}} - -## Configuring function runner to operate with private container registries +## 1. Configuring function runner to operate with private container registries This section describes how set up authentication for a private container registry containing kpt functions online e.g. (Github's GHCR) or locally e.g. (Harbor or Jfrog) that require authentication (username/password or token). @@ -22,7 +19,7 @@ To enable pulling of kpt function images from authenticated private registries b 1. Enabling the functionality using the argument *--enable-private-registries*. 2. Providing the path and name of the mounted secret using the arguments *--registry-auth-secret-path* and *--registry-auth-secret-name* respectively. -### Kubernetes secret setup for private registry using docker config +### 1.1 Kubernetes secret setup for private registry using docker config 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. @@ -63,7 +60,7 @@ metadata: type: kubernetes.io/dockerconfigjson ``` -### Mounting docker config secret to the function runner +### 1.2 Mounting docker config secret to the function runner Next you must mount the secret as a volume on the function runner deployment. Add the following sections to the Deployment object in the *2-function-runner.yaml* file: @@ -84,7 +81,7 @@ You may specify your desired paths for each `mountPath:` so long as the function 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 %}} -### Configuring function runner environment variables for private registries +### 1.3 Configuring function runner environment variables for private registries Lastly you must enable private registry functionality along with providing the path and name of the secret. Add the `--enable-private-registries`, `--registry-auth-secret-path` and `--registry-auth-secret-name` arguments to the function-runner Deployment object in the *2-function-runner.yaml* file: @@ -99,7 +96,7 @@ The `--enable-private-registries`, `--registry-auth-secret-path` and `--registry With this last step, if your Porch package uses kpt function images stored in an 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/). -## Configuring function runner to use custom TLS for private container registries +## 2. Configuring function runner to use custom TLS for private container registries If your private container registry uses a custom certificate for TLS authentication then extra configuration is required for the function runner to integrate with. See below @@ -107,7 +104,7 @@ If your private container registry uses a custom certificate for TLS authenticat 2. Mounting the secret containing the registries' TLS information to the function runner similarly to step 2. 3. Enabling TLS functionality and providing the path of the mounted secret to the function runner using the arguments *--enable-private-registries-tls* and *--tls-secret-path* respectively. -### Kubernetes secret layout for TLS certificate +### 2.1 Kubernetes secret layout for TLS certificate A typical secret containing TLS information will take on the a similar format to the following: @@ -126,7 +123,7 @@ type: kubernetes.io/tls The content in ** must be in PEM (Privacy Enhanced Mail) format, and the ** must be *ca.crt* or *ca.pem*. No other values are accepted. {{% /alert %}} -### Mounting TLS certificate secret to the function runner +### 2.2 Mounting TLS certificate secret to the function runner The TLS secret must then be mounted onto the function runner similarly to how the docker config secret was done previously [here](#mounting-docker-config-secret-to-the-function-runner). @@ -141,7 +138,7 @@ volumes: secretName: ``` -### Configuring function runner environment variables for TLS on private registries +### 2.3 Configuring function runner environment variables for TLS on private registries The *--enable-private-registries-tls* 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*. From f9dab9b42413b790a62c9d8ae17ca9b1c0a617be Mon Sep 17 00:00:00 2001 From: Catalin Stratulat Date: Wed, 20 Nov 2024 14:16:59 +0000 Subject: [PATCH 26/26] fixed broken section link --- .../porch/using-porch/using-authenticated-private-registries.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) 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 07d98f4f..4a92daff 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 @@ -125,7 +125,7 @@ The content in ** must be in PEM (Privacy Enhanced Mail) format, ### 2.2 Mounting TLS certificate secret to the function runner -The TLS secret must then be mounted onto the function runner similarly to how the docker config secret was done previously [here](#mounting-docker-config-secret-to-the-function-runner). +The TLS secret must then be mounted onto the function runner similarly to how the docker config secret was done previously in section 1.2 ```yaml volumeMounts: