From cdc1e7cc16cf259423335d535444b8c9e0653b66 Mon Sep 17 00:00:00 2001 From: Fang-Pen Lin Date: Mon, 24 Nov 2025 14:26:23 -0800 Subject: [PATCH] doc --- .../platform/pki/k8s-cert-manager.mdx | 345 +++++++++--------- 1 file changed, 176 insertions(+), 169 deletions(-) diff --git a/docs/documentation/platform/pki/k8s-cert-manager.mdx b/docs/documentation/platform/pki/k8s-cert-manager.mdx index 980a16973..7bbf183cb 100644 --- a/docs/documentation/platform/pki/k8s-cert-manager.mdx +++ b/docs/documentation/platform/pki/k8s-cert-manager.mdx @@ -49,198 +49,205 @@ The following steps show how to install cert-manager (using `kubectl`) and obtai - - Install `cert-manager` into your Kubernetes cluster by following the instructions [here](https://cert-manager.io/docs/installation/) or by running the following command: + - ```bash - kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.3/cert-manager.yaml - ``` - - - Start by creating a Kubernetes `Secret` containing the **EAB Secret** from step 1. As mentioned previously, this will be used by the Infisical PKI issuer to authenticate with Infisical. + Install cert-manager in your Kubernetes cluster by following the official guide [here](https://cert-manager.io/docs/installation/) or by applying the manifest directly: - - - ```bash - kubectl create secret generic infisical-acme-eab-secret \ - --namespace \ - --from-literal=eabSecret= - ``` - - - ```yaml acme-eab-secret.yaml - apiVersion: v1 - kind: Secret - metadata: - name: infisical-acme-eab-secret - namespace: - data: - eabSecret: - ``` + ```bash + kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.3/cert-manager.yaml + ``` - ```bash - kubectl apply -f acme-eab-secret.yaml - ``` - - - - - Next, create the cert-manager Issuer or ClusterIssuer by filling out `acme_server_url`, `your_email`, `acme_eab_kid`, and applying the following configuration file for the `Issuer` resource. - This configuration file specifies the connection details to your Infisical PKI CA to be used for issuing certificates. + + + Create a Kubernetes `Secret` that contains the **EAB Secret (HMAC key)** obtained in step 1. + cert-manager uses this secret to authenticate with the Infisical ACME server via External Account Binding (EAB). - ```yaml infisical-issuer.yaml - apiVersion: cert-manager.io/v1 - kind: Issuer - metadata: + + + ```bash + kubectl create secret generic infisical-acme-eab-secret \ + --namespace \ + --from-literal=eabSecret= + ``` + + + ```yaml acme-eab-secret.yaml + apiVersion: v1 + kind: Secret + metadata: + name: infisical-acme-eab-secret + namespace: + data: + eabSecret: + ``` + + ```bash + kubectl apply -f acme-eab-secret.yaml + ``` + + + + + + Next, create the cert-manager Issuer or ClusterIssuer by filling out `acme_server_url`, `your_email`, `acme_eab_kid`, and applying the following configuration file for the `Issuer` resource. + This configuration file specifies the connection details to your Infisical PKI CA to be used for issuing certificates. + + ```yaml infisical-issuer.yaml + apiVersion: cert-manager.io/v1 + kind: Issuer + metadata: + name: issuer-infisical + spec: + acme: + # the URL of your Infisical certificate profile with + # ACME enrollment method from step 1 + server: + # your email address, any email could work. + # currently we just ignore the value + email: + externalAccountBinding: + keyID: # the EAB secret value from step 1 + keySecretRef: # reference to the Secret created in step 3 + name: "issuer-infisical-client-secret" + key: "clientSecret" + privateKeySecretRef: + name: issuer-infisical-account-key + solvers: + - http01: + ingress: + # this doesn't need to be nginx, you can use any + # ingressClassName available in your Kubernetes cluster + ingressClassName: nginx + ``` + + ``` + kubectl apply -f infisical-issuer.yaml + ``` + + You can check that the issuer was created successfully by running the following command: + + ```bash + kubectl get issuers.cert-manager.io -n -o wide + ``` + + ```bash + NAME AGE + issuer-infisical 21h + ``` + + + An `Issuer` is a namespaced resource, and it is not possible to issue certificates from an `Issuer` in a different namespace. + This means you will need to create an `Issuer` in each namespace you wish to obtain `Certificates` in. + + If you want to create a single `Issuer` that can be consumed in multiple namespaces, you should consider creating a `ClusterIssuer` resource. This is almost identical to the `Issuer` resource, however is non-namespaced so it can be used to issue `Certificates` across all namespaces. + + You can read more about the `Issuer` and `ClusterIssuer` resources [here](https://cert-manager.io/docs/configuration/). + + Also, currently Infisical ACME server only supports HTTP-01 and requires all the certificate orders passing the challenge before issuing certificates. + We will allow users to opt-out challenge in the near future and also provide support DNS-01 as well. + + + + + + Finally, create a `Certificate` by applying the following configuration file. + This configuration file specifies the details of the (end-entity/leaf) certificate to be issued. + + ```yaml certificate-issuer.yaml + apiVersion: cert-manager.io/v1 + kind: Certificate + metadata: + name: certificate-by-issuer + namespace: + spec: + # the common name for the certificate + commonName: certificate-by-issuer.example.com + # the name of the Kubernetes Secret to create and store + # the certificate and private key in + secretName: certificate-by-issuer + issuerRef: name: issuer-infisical - spec: - acme: - # the URL of your Infisical certificate profile with - # ACME enrollment method from step 1 - server: - # your email address, any email could work. - # currently we just ignore the value - email: - externalAccountBinding: - keyID: # the EAB secret value from step 1 - keySecretRef: # reference to the Secret created in step 3 - name: "issuer-infisical-client-secret" - key: "clientSecret" - privateKeySecretRef: - name: issuer-infisical-account-key - solvers: - - http01: - ingress: - # this doesn't need to be nginx, you can use any - # ingressClassName available in your Kubernetes cluster - ingressClassName: nginx - ``` + group: issuers.cert-manager.io + kind: Issuer + # the algorithm and key size to use + privateKey: + algorithm: ECDSA + size: 256 + # the ttl for the certificate + duration: 48h + # the time before the certificate expiry that the certificate should + # be automatically renewed + renewBefore: 12h + ``` - ``` - kubectl apply -f infisical-issuer.yaml - ``` + The above sample configuration file specifies a certificate to be issued with the common name `certificate-by-issuer.example.com` and ECDSA private key using the P-256 curve, valid for 48 hours; the certificate will be automatically renewed by `cert-manager` 12 hours before expiry. + The certificate is issued by the issuer `issuer-infisical` created in the previous step and the resulting certificate and private key will be stored in a secret named `certificate-by-issuer`. - You can check that the issuer was created successfully by running the following command: + Note that the full list of the fields supported on the `Certificate` resource can be found in the API reference documentation [here](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.CertificateSpec). - ```bash - kubectl get issuers.cert-manager.io -n -o wide - ``` + You can check that the certificate was created successfully by running the following command: - ```bash - NAME AGE - issuer-infisical 21h - ``` + ```bash + kubectl get certificates -n -o wide + ``` - - An `Issuer` is a namespaced resource, and it is not possible to issue certificates from an `Issuer` in a different namespace. - This means you will need to create an `Issuer` in each namespace you wish to obtain `Certificates` in. + ```bash + NAME READY SECRET ISSUER STATUS AGE + certificate-by-issuer True certificate-by-issuer issuer-infisical Certificate is up to date and has not expired 20h + ``` - If you want to create a single `Issuer` that can be consumed in multiple namespaces, you should consider creating a `ClusterIssuer` resource. This is almost identical to the `Issuer` resource, however is non-namespaced so it can be used to issue `Certificates` across all namespaces. + + + Since the actual certificate and private key are stored in a Kubernetes secret, we can check that the secret was created successfully by running the following command: - You can read more about the `Issuer` and `ClusterIssuer` resources [here](https://cert-manager.io/docs/configuration/). + ```bash + kubectl get secret certificate-by-issuer -n + ``` - Also, currently Infisical ACME server only supports HTTP-01 and requires all the certificate orders passing the challenge before issuing certificates. - We will allow users to opt-out challenge in the near future and also provide support DNS-01 as well. - - - + ```bash + NAME TYPE DATA AGE + certificate-by-issuer kubernetes.io/tls 2 26h + ``` - Finally, create a `Certificate` by applying the following configuration file. - This configuration file specifies the details of the (end-entity/leaf) certificate to be issued. + We can `describe` the secret to get more information about it: - ```yaml certificate-issuer.yaml - apiVersion: cert-manager.io/v1 - kind: Certificate - metadata: - name: certificate-by-issuer - namespace: - spec: - # the common name for the certificate - commonName: certificate-by-issuer.example.com - # the name of the Kubernetes Secret to create and store - # the certificate and private key in - secretName: certificate-by-issuer - issuerRef: - name: issuer-infisical - group: issuers.cert-manager.io - kind: Issuer - # the algorithm and key size to use - privateKey: - algorithm: ECDSA - size: 256 - # the ttl for the certificate - duration: 48h - # the time before the certificate expiry that the certificate should - # be automatically renewed - renewBefore: 12h - ``` + ```bash + kubectl describe secret certificate-by-issuer -n default + ``` - The above sample configuration file specifies a certificate to be issued with the common name `certificate-by-issuer.example.com` and ECDSA private key using the P-256 curve, valid for 48 hours; the certificate will be automatically renewed by `cert-manager` 12 hours before expiry. - The certificate is issued by the issuer `issuer-infisical` created in the previous step and the resulting certificate and private key will be stored in a secret named `certificate-by-issuer`. + ```bash + Name: certificate-by-issuer + Namespace: default + Labels: controller.cert-manager.io/fao=true + Annotations: cert-manager.io/alt-names: + cert-manager.io/certificate-name: certificate-by-issuer + cert-manager.io/common-name: certificate-by-issuer.example.com + cert-manager.io/ip-sans: + cert-manager.io/issuer-group: issuers.cert-manager.io + cert-manager.io/issuer-kind: Issuer + cert-manager.io/issuer-name: issuer-infisical + cert-manager.io/uri-sans: - Note that the full list of the fields supported on the `Certificate` resource can be found in the API reference documentation [here](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.CertificateSpec). + Type: kubernetes.io/tls - You can check that the certificate was created successfully by running the following command: + Data + ==== + ca.crt: 1306 bytes + tls.crt: 2380 bytes + tls.key: 227 bytes + ``` - ```bash - kubectl get certificates -n -o wide - ``` + Here, `ca.crt` is the Root CA certificate, `tls.crt` is the requested certificate followed by the certificate chain, and `tls.key` is the private key for the certificate. - ```bash - NAME READY SECRET ISSUER STATUS AGE - certificate-by-issuer True certificate-by-issuer issuer-infisical Certificate is up to date and has not expired 20h - ``` - - - Since the actual certificate and private key are stored in a Kubernetes secret, we can check that the secret was created successfully by running the following command: + We can decode the certificate and print it out using `openssl`: - ```bash - kubectl get secret certificate-by-issuer -n - ``` + ```bash + kubectl get secret certificate-by-issuer -n default -o jsonpath='{.data.tls\.crt}' | base64 --decode | openssl x509 -text -noout + ``` - ```bash - NAME TYPE DATA AGE - certificate-by-issuer kubernetes.io/tls 2 26h - ``` + In any case, the certificate is ready to be used as Kubernetes Secret by your Kubernetes resources. - We can `describe` the secret to get more information about it: - - ```bash - kubectl describe secret certificate-by-issuer -n default - ``` - - ```bash - Name: certificate-by-issuer - Namespace: default - Labels: controller.cert-manager.io/fao=true - Annotations: cert-manager.io/alt-names: - cert-manager.io/certificate-name: certificate-by-issuer - cert-manager.io/common-name: certificate-by-issuer.example.com - cert-manager.io/ip-sans: - cert-manager.io/issuer-group: issuers.cert-manager.io - cert-manager.io/issuer-kind: Issuer - cert-manager.io/issuer-name: issuer-infisical - cert-manager.io/uri-sans: - - Type: kubernetes.io/tls - - Data - ==== - ca.crt: 1306 bytes - tls.crt: 2380 bytes - tls.key: 227 bytes - ``` - - Here, `ca.crt` is the Root CA certificate, `tls.crt` is the requested certificate followed by the certificate chain, and `tls.key` is the private key for the certificate. - - We can decode the certificate and print it out using `openssl`: - - ```bash - kubectl get secret certificate-by-issuer -n default -o jsonpath='{.data.tls\.crt}' | base64 --decode | openssl x509 -text -noout - ``` - - In any case, the certificate is ready to be used as Kubernetes Secret by your Kubernetes resources. - +