chore(docs): add updated documentation for configmaps in trust-manager docs and root

irby · irby · commit 837328cf1255 · 2026-01-21T11:58:36.000-05:00
Signed-off-by: Matthew H. Irby &lt;matt.irby@keyfactor.com&gt;
diff --git a/Makefile b/Makefile
@@ -67,7 +67,7 @@ test: manifests generate fmt vet envtest ## Run tests.
 # Utilize Kind or modify the e2e tests to load the image locally, enabling compatibility with other vendors.
 .PHONY: test-e2e  # Run the e2e tests against a Kind k8s instance that is spun up.
 test-e2e:
-	source e2e/.env && ./e2e/run_tests.sh
+	cd e2e && source .env && ./run_tests.sh
 
 .PHONY: lint
 lint: golangci-lint ## Run golangci-lint linter & yamllint
diff --git a/docs/ca-bundle/README.md b/docs/ca-bundle/README.md
@@ -4,13 +4,15 @@ The command-cert-manager-issuer integration requires a secure, trusted connectio
 
 ## Using Self-Signed Certificates
 
-If the targeted Keyfactor Command API is configured to use a self-signed certificate or with a certificate whose issuer isn't widely trusted, the CA certificate **must be provided** as a Kubernetes secret. The secret must belong to the same namespace that command-cert-manager-issuer is deployed to (i.e. `command-issuer-system`). 
+If the targeted Keyfactor Command API is configured to use a self-signed certificate or with a certificate whose issuer isn't widely trusted, the CA certificate **must be provided** via a Kubernetes Secret of ConfigMap. The secret must belong to the same namespace that command-cert-manager-issuer is deployed to (i.e. `command-issuer-system`). 
 
 ```shell
 kubectl -n command-issuer-system create secret generic command-ca-secret --from-file=ca.crt
+
+kubectl -n command-issuer-system create configmap command-ca --from-file=ca.crt
 ```
 
-In the issuer specification, reference the created secret with the `caSecretName` field. The issuer resource does not need to belong to the same namespace as the secret.
+In the Issuer / ClusterIssuer specification, reference the created resource.
 
 ```yaml
  apiVersion: command-issuer.keyfactor.com/v1alpha1
@@ -20,22 +22,28 @@ In the issuer specification, reference the created secret with the `caSecretName
    namespace: default
  spec:
    ...
-   caSecretName: "command-ca-secret"
+   caSecretName: "command-ca-secret" # if using Kubernetes Secret
+   caBundleConfigMapName: "command-ca" # if using Kubernetes ConfigMap
+   caBundleKey: "ca.crt" # optional key name, pulls the last key in resource if not specified
 ```
 
 ## Using Publicly Trusted Certificates
 
-If the targeted Keyfactor Command API is configured with a publicly trusted certificate authority (Sectigo / LetsEncrypt / etc.), the command-cert-manager-issuer image is built with a pre-bundled trust store of publicly trusted certificates but with a ***very important caveat***. The trust store may become out-of-sync over time, especially if the certificate authority issuing the Keyfactor Command certificate is updated.
+If the targeted Keyfactor Command API is configured with a publicly trusted certificate authority (Sectigo / LetsEncrypt / etc.), the command-cert-manager-issuer container image is built with a pre-bundled trust store of publicly trusted certificates but with a ***very important caveat***. The trust store may become out-of-sync over time, especially if the certificate authority issuing the Keyfactor Command certificate is updated.
 
-It is not required to use the `caSecretName` specification, but it is **recommended** to maintain a list of trusted certificates instead of relying on the pre-bundled certificate store when the command-cert-manager-issuer image is created. This will reduce the likelihood of connectivity issues if the Keyfactor Command instance is updated to use a new CA or if the command-cert-manager-issuer image is updated and it does not include the Command CA in its trust store.
+It is **not required** to use the `caSecretName` / `caBundleConfigMapName` specification if Keyfactor Command's TLS certificate is built using a publicly trusted root, but it is **recommended for production workloads to maintain a list of trusted certificates** instead of relying on the pre-bundled certificate store when the command-cert-manager-issuer image is created. This will reduce the likelihood of connectivity issues if the Keyfactor Command instance is updated to use a new CA or if the command-cert-manager-issuer image is updated and it does not include the Keyfactor Command TLS certificate's root CA in its trust store.
 
 This document covers available tools to help manage CA trust bundles.
 
 ### trust-manager
 
-[trust-manager](https://cert-manager.io/docs/trust/trust-manager/) can be used to sync CA trust bundles in a Kubernetes cluster. trust-manager can synchronize a list of publicly trusted CAs as well as any custom CAs to be included in the trust chain.
+[trust-manager](https://cert-manager.io/docs/trust/trust-manager/) can be used to sync CA trust bundles in a Kubernetes cluster. trust-manager can synchronize a list of publicly trusted CAs as well as any custom CAs to be included in the trust chain. It is recommended to add your Keyfactor Command's intermediate and root CAs to a Kubernetes Secret / ConfigMap and synchronize this with the trust-manager bundle.
+
+The publicly trusted certificates are tied to the trust-manager image. To pull up-to-date publicly trusted CAs, update the trust-manager deployment to the latest version.
+
+trust-manager can synchronize the CA trust bundle to either a Kubernetes Secret or ConfigMap, this documentation will cover both methods.
 
-TODO: trust-manager also supports configMap targets, which are more secure to write to with better RBAC policy.
+> NOTE: For the latest documentation and installation instructions, please refer to the [cert-manager trust-manager documentation](https://cert-manager.io/docs/trust/trust-manager/installation/). The instructions below may become outdated over time.
 
 #### Pre-requisites
 
@@ -44,26 +52,132 @@ TODO: trust-manager also supports configMap targets, which are more secure to wr
 
 #### Security Considerations
 
-> ⚠️ Important: Required Permissions
+> ⚠️ Important: Required Permissions. Please Read!
+
+trust-manager requires different permission scopes depending on your synchronization target:
+
+**Synchronizing to ConfigMaps (Recommended):**
+- ✅ Only requires cluster-wide **read** access to ConfigMaps
+- ✅ Lower security risk
+- ✅ Suitable for most environments
 
-trust-manager requires **cluster-wide read access** to secrets. This is a hard technical requirement of trust-manager's architecture.
+**Synchronizing to Secrets:**
+- ⚠️ Requires cluster-wide **read** access to **all Secrets**
+- ⚠️ Higher security risk - trust-manager can read any secret in the cluster
+- ⚠️ Requires explicit RBAC configuration (shown below)
+- ⚠️ Only use if you have specific requirements for Secret storage
 
-| Permission Type | Scope              | Resources           | Verbs                         | Purpose                           |
-| --------------- | ------------------ | ------------------- | ----------------------------- | --------------------------------- |
-| **Read**        | Cluster-wide       | secrets, configmaps | get, list, watch              | Discover sources, monitor targets |
-| **Write**       | Namespace-specific | secrets             | create, update, patch, delete | Deploy CA bundles                 |
+**Permission Summary:**
 
-#### Setting up trust-manager
+| Target Type | Read Scope     | Write Scope        | Security Impact |
+|-------------|----------------|--------------------|-----------------| 
+| ConfigMap   | ConfigMaps     | Namespace-specific | Low             |
+| Secret      | **All Secrets**| Namespace-specific | High            |
 
-> NOTE: The below instructions are subject to become outdated over time. Please always refer to the [cert-manager](https://cert-manager.io/docs/trust/trust-manager/installation/) documentation for updated installation instructions.
+For most deployments, **Option 1 (ConfigMap)** is recommended unless you have compliance requirements mandating Secret storage.
+
+#### Option 1: Synchronizing to a ConfigMap
+
+##### Setting up trust-manager
 
 1. Install trust-manager
 
     ```bash
     # Install trust-manager in the cert-manager namespace
     helm install trust-manager oci://quay.io/jetstack/charts/trust-manager \
       --namespace cert-manager \
-      --set secretTargets.enabled=true \ # required trust-manager to write to Kubernetes secrets
+      --create-namespace \
+      --wait
+    ```
+2. Create a ConfigMap from a PEM file
+
+   Create a ConfigMap containing the PEM of the CA certificates you want to trust. Create the ConfigMap in the same namespace trust-manager is deployed to.
+
+   ```bash
+   kubectl create configmap enterprise-root-ca \
+        --from-file=ca.crt=/path/to/root-ca.pem \
+        --namespace=cert-manager \
+        --dry-run=client -o yaml | kubectl apply -f -
+   ```
+
+3. Label target namespaces
+
+    Label the namespace command-cert-manager-issuer is deployed to annotate trust-manager should write ConfigMaps to it
+
+    ```bash
+    kubectl label namespace command-issuer-system command-issuer-ca-bundle=enabled # change to your namespace
+    ```
+
+4. Create a Bundle
+
+    Create a bundle resource to tell trust-manager what ConfigMaps to synchronize and whether to include publicly trusted CAs as part of the sync.
+
+    ```yaml
+    kubectl apply -f - <<EOF
+    apiVersion: trust.cert-manager.io/v1alpha1
+    kind: Bundle
+    metadata:
+      name: command-issuer-ca-bundle
+    spec:
+      sources:
+      - useDefaultCAs: true # determines whether to bundle publicly trusted certificates used to validate most TLS certificates on the internet (Let's Encrypt, Google, Amazon, etc.)
+    
+      - configMap:
+          name: "enterprise-root-ca"
+          key: "ca.crt"
+
+      # Additional intermediate or partner CAs (can also target Secrets in the same namespace)
+      #- secret:
+      #    name: "enterprise-ca-bundle"
+      #    key: "ca.crt"
+    
+      target:
+        configMap:
+          key: "ca.crt"
+
+        # Distribute to all namespaces with this label
+        namespaceSelector:
+          matchLabels:
+            command-issuer-ca-bundle: "enabled"
+      EOF
+    ```
+
+##### Using the trust bundle
+
+Once the setup is complete, trust-manager will create a resource in the target namespace:
+- **Resource name:** Matches the Bundle metadata name (`command-issuer-ca-bundle` in this example)
+- **Namespace:** Any namespace matching the `namespaceSelector` label
+- **Key:** As specified in `target.configMap.key`
+
+You can verify the resource was created:
+````bash
+kubectl get configmap -n command-issuer-system command-issuer-ca-bundle
+````
+
+In your issuer specification (Issuer/ClusterIssuer), reference the ConfigMap in the `caBundleConfigMapName` specification field:
+
+```yaml
+ apiVersion: command-issuer.keyfactor.com/v1alpha1
+ kind: Issuer # or ClusterIssuer
+ metadata:
+   ...
+ spec:
+   ...
+   caBundleConfigMapName: "command-issuer-ca-bundle"
+   caBundleKey: "ca.crt" # optional key name, pulls the last key in resource if not specified
+```
+
+#### Option 2: Synchronizing to a Secret
+
+##### Setting up trust-manager
+
+1. Install trust-manager
+
+    ```bash
+    # Install trust-manager in the cert-manager namespace
+    helm install trust-manager oci://quay.io/jetstack/charts/trust-manager \
+      --namespace cert-manager \
+      --set secretTargets.enabled=true \
       --create-namespace \
       --wait
     ```
@@ -139,7 +253,7 @@ Due to Kubernetes constraints, writing to secrets outside of trust-manager's nam
     rules:
     - apiGroups: [""]
       resources: ["secrets"]
-        verbs: ["create", "update", "patch", "delete"]
+      verbs: ["create", "update", "patch", "delete", "read"]
     ---
     apiVersion: rbac.authorization.k8s.io/v1
     kind: RoleBinding
@@ -161,6 +275,7 @@ Due to Kubernetes constraints, writing to secrets outside of trust-manager's nam
     Create a bundle resource to tell trust-manager what secrets to synchronize and whether to include publicly trusted CAs as part of the sync.
 
     ```yaml
+    kubectl apply -f - <<EOF
     apiVersion: trust.cert-manager.io/v1alpha1
     kind: Bundle
     metadata:
@@ -173,8 +288,8 @@ Due to Kubernetes constraints, writing to secrets outside of trust-manager's nam
           name: "enterprise-root-ca"
           key: "ca.crt"
 
-      # Additional intermediate or partner CAs
-      #- secret:
+      # Additional intermediate or partner CAs (can also target ConfigMaps in the same namespace)
+      #- configMap:
       #    name: "enterprise-ca-bundle"
       #    key: "ca.crt"
     
@@ -186,11 +301,20 @@ Due to Kubernetes constraints, writing to secrets outside of trust-manager's nam
         namespaceSelector:
           matchLabels:
             command-issuer-ca-bundle: "enabled"
+      EOF
     ```
 
-#### Using the trust bundle
+##### Using the trust bundle
+
+Once the setup is complete, trust-manager will create a resource in the target namespace:
+- **Resource name:** Matches the Bundle metadata name (`command-issuer-ca-bundle` in this example)
+- **Namespace:** Any namespace matching the `namespaceSelector` label
+- **Key:** As specified in `target.secret.key`
 
-Once the setup is complete, a Kubernetes secret called `command-issuer-ca-bundle` will appear in the desired namespace (i.e. `command-issuer-system`) and the trusted CA bundle will appear in the `ca.crt` key.
+You can verify the resource was created:
+````bash
+kubectl get secret -n command-issuer-system command-issuer-ca-bundle
+````
 
 In your issuer specification (Issuer/ClusterIssuer), reference the secret in the `caSecretName` specification field:
 
@@ -202,4 +326,5 @@ In your issuer specification (Issuer/ClusterIssuer), reference the secret in the
  spec:
    ...
    caSecretName: "command-issuer-ca-bundle"
+   caBundleKey: "ca.crt" # optional key name, pulls the last key in resource if not specified
 ```
diff --git a/docsource/content.md b/docsource/content.md
@@ -222,6 +222,8 @@ For example, ClusterIssuer resources can be used to issue certificates for resou
     | apiPath                 | (optional) The base path of the Command REST API. Defaults to `KeyfactorAPI`.                                                                                                           |
     | commandSecretName          | (optional) The name of the Kubernetes secret containing basic auth credentials or OAuth 2.0 credentials. Omit if using ambient credentials.                                         |
     | caSecretName       | (optional) The name of the Kubernetes secret containing the CA certificate trust chain. See the [CA Bundle docs](./docs/ca-bundle/README.md) for more information.      |
+    | caBundleConfigMapName       | (optional) The name of the Kubernetes ConfigMap containing the CA certificate trust chain. See the [CA Bundle docs](./docs/ca-bundle/README.md) for more information.      |
+    | caBundleKey | (optional) The name of the key in the ConfigMap or Secret specified by `caSecretName` or `caBundleConfigMapName` that contains the CA bundle. If omitted, the last key of the ConfigMap / Secret resource will be used. |
     | certificateAuthorityLogicalName | The logical name of the Certificate Authority to use in Command. For example, `Sub-CA`                                                              |
     | certificateAuthorityHostname   | (optional) The hostname of the Certificate Authority specified by `certificateAuthorityLogicalName`. This field is usually only required if the CA in Command is a DCOM (MSCA-like) CA.                                                                     |
     | enrollmentPatternId     | The ID of the [Enrollment Pattern](https://software.keyfactor.com/Core-OnPrem/Current/Content/ReferenceGuide/Enrollment-Patterns.htm) to use when this Issuer/ClusterIssuer enrolls CSRs. **Supported by Keyfactor Command 25.1 and above**. If `certificateTemplate` and `enrollmentPatternId` are both specified, the enrollment pattern parameter will take precedence. If `enrollmentPatternId` and `enrollmentPatternName` are both specified, `enrollmentPatternId` will take precedence. Enrollment will fail if the specified certificate template is not compatible with the enrollment pattern.                                                                        |
@@ -251,7 +253,9 @@ For example, ClusterIssuer resources can be used to issue certificates for resou
           hostname: "$HOSTNAME"
           apiPath: "/KeyfactorAPI" # Preceding & trailing slashes are handled automatically
           commandSecretName: "command-secret" # references the secret created above. Omit if using ambient credentials.
-          caSecretName: "command-ca-secret" # references a secret containing the CA trust chain (see CA Bundle docs for more info)
+          # caSecretName: "command-ca-secret" # references a secret containing the CA trust chain (see CA Bundle docs for more info)
+          # caBundleConfigMapName: "command-ca-configmap" # references a configmap containing the CA trust chain (see CA Bundle docs for more info)
+          # caBundleKey: "ca.crt" # references the key in the secret/configmap containing the CA trust chain (see CA Bundle docs for more info)
 
           # certificateAuthorityHostname: "$COMMAND_CA_HOSTNAME" # Uncomment if required
           certificateAuthorityLogicalName: "$COMMAND_CA_LOGICAL_NAME"
@@ -281,7 +285,9 @@ For example, ClusterIssuer resources can be used to issue certificates for resou
           hostname: "$HOSTNAME"
           apiPath: "/KeyfactorAPI" # Preceding & trailing slashes are handled automatically 
           commandSecretName: "command-secret" # references the secret created above. Omit if using ambient credentials.
-          caSecretName: "command-ca-secret" # references a secret containing the CA trust chain (see CA Bundle docs for more info)
+          # caSecretName: "command-ca-secret" # references a secret containing the CA trust chain (see CA Bundle docs for more info)
+          # caBundleConfigMapName: "command-ca-configmap" # references a configmap containing the CA trust chain (see CA Bundle docs for more info)
+          # caBundleKey: "ca.crt" # references the key in the secret/configmap containing the CA trust chain (see CA Bundle docs for more info)
 
           # certificateAuthorityHostname: "$COMMAND_CA_HOSTNAME" # Uncomment if required
           certificateAuthorityLogicalName: "$COMMAND_CA_LOGICAL_NAME"
