diff --git a/README.md b/README.md index e527213..b3e0de2 100644 --- a/README.md +++ b/README.md @@ -22,17 +22,11 @@ helm install stackit-cert-manager-webhook --namespace cert-manager stackit-cert- ## Usage -1. ***Initiation of STACKIT Authentication Token Secret:*** +1. ***Initiation of STACKIT Service Account Secret:*** ```bash kubectl create secret generic stackit-sa-authentication \ -n cert-manager \ - --from-literal=auth-token= - ``` - Or alternatively we can utilize the STACKIT service account path authentication: - ``` - kubectl create secret generic stackit-sa-authentication \ - -n cert-manager \ - --from-literal=sa.json='{ + --from-literal=sa.json='{ "id": "4e1fe486-b463-4bcd-9210-288854268e34", "publicKey": "-----BEGIN PUBLIC KEY-----\nPUBLIC_KEY\n-----END PUBLIC KEY-----", "createdAt": "2024-04-02T13:12:17.678+00:00", @@ -80,14 +74,7 @@ helm install stackit-cert-manager-webhook --namespace cert-manager stackit-cert- projectId: ``` - For diverse project architectures where zones are spread across varying projects, necessitating distinct - authentication tokens per project, the Issuer configuration becomes pertinent. This approach inherently - tethers namespaces to individual projects. - ```bash - kubectl create secret generic stackit-cert-manager-webhook \ - --namespace=default \ - --from-literal=auth-token= - ``` + For diverse project architectures where zones are spread across varying projects, use an Issuer (namespaces are separate): ```yaml apiVersion: cert-manager.io/v1 kind: Issuer @@ -107,10 +94,21 @@ helm install stackit-cert-manager-webhook --namespace cert-manager stackit-cert- groupName: acme.stackit.de config: projectId: - authTokenSecretNamespace: default ``` - *Note:* Ensure the creation of an authentication token secret within the namespace linked to the issuer. - The secret must be vested with permissions to access zones in the stipulated project configuration. + *Note on service accounts and namespaces:* + - Issuer-per-namespace (recommended for isolation): create a STACKIT service-account key (sa.json) for each STACKIT project you need to manage and place that key in a Kubernetes Secret in the same namespace as the Issuer. This means one sa.json (one SA key) per Issuer/namespace when the Issuers target different STACKIT projects. + Example (create a secret in the Issuer namespace): + ```bash + kubectl create secret generic stackit-sa-authentication \ + -n \ + --from-literal=sa.json='{"id":"...","credentials":{...}}' + ``` + Ensure the webhook can read the secret in that namespace (create the secret where the Issuer lives). + - Alternative (single SA key for multiple projects): you can grant the service account broader permissions at folder or organization level so one sa.json can manage zones across multiple projects. This is more convenient but grants wider access — evaluate security and follow least-privilege principles. + - Tradeoffs: + - Per-namespace/per-project SA keys: better isolation and least privilege, easier to rotate keys per project. + - Folder/org-level SA key: lower operational overhead (single key), but larger blast radius if compromised. + 3. ***Demonstration of Ingress Integration with Wildcard SSL/TLS Certificate Generation*** Given the preceding configuration, it is possible to exploit the capabilities of the Issuer or ClusterIssuer to dynamically produce wildcard SSL/TLS certificates in the following manner: @@ -181,9 +179,6 @@ spec: config: projectId: string apiBasePath: string - authTokenSecretRef: string - authTokenSecretKey: string - authTokenSecretNamespace: string serviceAccountKeyPath: string serviceAccountBaseUrl: string acmeTxtRecordTTL: int64 @@ -191,10 +186,6 @@ spec: - projectId: The unique identifier for the STACKIT project. - apiBasePath: The base path for the STACKIT DNS API. (Default: https://dns.api.stackit.cloud) -- authTokenSecretRef: The reference to the secret containing the STACKIT authentication token. (Default: - stackit-cert-manager-webhook) -- authTokenSecretKey: The key within the secret containing the STACKIT authentication token. (Default: auth-token) -- authTokenSecretNamespace: The namespace of the secret containing the STACKIT authentication token. (Default: cert-manager) - serviceAccountKeyPath: The path to the service account key file. The file must be mounted into the container. - serviceAccountBaseUrl: The base URL for the STACKIT service account API. (Default: https://service-account.api.stackit.cloud/token) - acmeTxtRecordTTL: The TTL for the ACME TXT record. (Default: 600)