awatertrevi/infisical
1
0
Fork 0
mirror of https://github.com/awatertrevi/infisical.git synced 2026-09-22 13:39:35 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge pull request #4932 from Infisical/PKI-59-update-acme-docs

Browse Source 
[PKI-59] Update ACME docs
This commit is contained in:
BlackMagiq
2025-11-25 00:07:50 -05:00
committed by GitHub
parent d56ebe989d ae948fcde0
commit 0d62ef6fb5
11 changed files with 295 additions and 329 deletions
Download Patch File Download Diff File Expand all files Collapse all files

2
docs/docs.json
View File

@@ -752,7 +752,7 @@
{
"group": "Infrastructure Integrations",
"pages": [
"documentation/platform/pki/pki-issuer",
"documentation/platform/pki/k8s-cert-manager",
"documentation/platform/pki/integration-guides/gloo-mesh",
"documentation/platform/pki/integration-guides/windows-server-acme",
"documentation/platform/pki/integration-guides/nginx-certbot",

2
docs/documentation/getting-started/concepts/client-integrations.mdx
View File

@@ -24,7 +24,7 @@ Infisical offers a non-exhaustive set of clients and interfaces to support a wid
- [External Secrets Operator (ESO)](https://external-secrets.io/latest/provider/infisical): Allows Infisical to act as a backend provider for syncing secrets into Kubernetes `Secret` objects using the widely adopted External Secrets Operator.
- [Kubernetes PKI Issuer](/documentation/platform/pki/pki-issuer): A controller that issues X.509 certificates from Infisical PKI using the cert-manager Issuer and Certificate CRDs.
- [Kubernetes cert-manager](/documentation/platform/pki/k8s-cert-manager): A controller that issues X.509 certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles) using the cert-manager Issuer and Certificate CRDs.
- [Secret Syncs](/integrations/secret-syncs/overview): Native integrations to forward secrets to services like GitHub, GitLab, AWS Secrets Manager, Vercel, and more.

2
docs/documentation/platform/pki/enrollment-methods/acme.mdx
View File

@@ -5,7 +5,7 @@ sidebarTitle: "ACME"
## Concept
The ACME enrollment method allows you to issue and manage certificates against a specific [certificate profile](/documentation/platform/pki/certificates/profiles) using the [ACME protocol](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment).
The ACME enrollment method allows Infisical to act as an ACME server. It lets you request and manage certificates against a specific [certificate profile](/documentation/platform/pki/certificates/profiles) using the [ACME protocol](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment).
This method is suitable for web servers, load balancers, and other general-purpose servers that can run an [ACME client](https://letsencrypt.org/docs/client-options/) for automated certificate management.
Infisical's ACME enrollment method is based on [RFC 8555](https://datatracker.ietf.org/doc/html/rfc8555/).

7
docs/documentation/platform/pki/integration-guides/apache-certbot.mdx
View File

@@ -1,9 +1,9 @@
---
title: "Apache Server"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Apache Server with Certbot"
description: "Learn how to issue TLS certificates from Infisical using ACME enrollment on Apache Server with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Apache HTTP Server](https://httpd.apache.org/).
This guide demonstrates how to use Infisical to issue TLS certificates for your [Apache HTTP Server](https://httpd.apache.org/).
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). Apache benefits from excellent Certbot integration, allowing both certificate-only mode and automatic SSL configuration.
@@ -182,4 +182,5 @@ Before you begin, make sure you have:
</Note>
</Step>
</Steps>
</Steps>

16
docs/documentation/platform/pki/integration-guides/gloo-mesh.mdx
View File

@@ -1,13 +1,13 @@
---
title: "Gloo Mesh"
description: "Learn how to automatically provision and manage Istio intermediate CA certificates for Gloo Mesh using Infisical PKI"
description: "Learn how to automatically provision and manage Istio intermediate CA certificates for Gloo Mesh using Infisical"
---
This guide will provide a high level overview on how you can use Infisical PKI and cert-manager to issue Istio intermediate CA certificates for your Gloo Mesh workload clusters. For more background about Istio certificates, see the [Istio CA overview](https://istio.io/latest/docs/concepts/security/#pki).
This guide will provide a high level overview on how you can use Infisical and [cert-manager](https://cert-manager.io/) to issue Istio intermediate CA certificates for your Gloo Mesh workload clusters. For more background about Istio certificates, see the [Istio CA overview](https://istio.io/latest/docs/concepts/security/#pki).
## Overview
In this setup, we will use Infisical PKI to generate and store your root CA and subordinate CAs that are used to generate Istio intermediate CAs for your Gloo Mesh workload clusters.
In this setup, we will use Infisical to generate and store your root CA and subordinate CAs that are used to generate Istio intermediate CAs for your Gloo Mesh workload clusters.
To manage the lifecycle of Istio intermediate CA certificates, you'll also install [cert-manager](https://cert-manager.io/).
Cert-manager is a Kubernetes controller that helps you automate the process of obtaining and renewing certificates from various PKI providers.
@@ -21,19 +21,19 @@ With this approach, you get the following benefits:
## General Setup
The certificate provisioning workflow begins with setting up your PKI hierarchy in Infisical, where you create root and subordinate certificate authorities.
When you deploy a `Certificate` CRD in your workload cluster, `cert-manager` uses the Infisical PKI Issuer controller to authenticate with Infisical using machine identity credentials and request an intermediate CA certificate.
When you deploy a `Certificate` CRD in your workload cluster, `cert-manager` uses the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles) to authenticate using EAB credentials and request an intermediate CA certificate.
Infisical verifies the request against your certificate templates and returns the signed certificate.
From there, Istio's control plane will automatically use this intermediate CA to sign leaf certificates for workloads in the service mesh, enabling secure mTLS communication across your entire Gloo Mesh infrastructure.
Follow the [Infisical PKI Issuer guide](/documentation/platform/pki/pki-issuer) for detailed instructions on how to set up the Infisical PKI Issuer and cert-manager for your Istio intermediate CA certificates in Gloo Mesh clusters.
Follow the [Kubernetes cert-manager guide](/documentation/platform/pki/k8s-cert-manager) for detailed instructions on how to set up the Infisical and cert-manager for your Istio intermediate CA certificates in Gloo Mesh clusters.
For Gloo Mesh-specific configuration, ensure that:
- The Certificate resource targets the `istio-system` namespace with `secretName: cacerts`
- Certificate templates in Infisical PKI are configured for intermediate CA usage with appropriate key usage and constraints
- Multiple workload clusters use the same Infisical PKI root to enable cross-cluster mTLS communication
- Certificate profiles in Infisical are configured for intermediate CA usage with appropriate key usage and constraints
- Multiple workload clusters use the same Infisical root to enable cross-cluster mTLS communication
## Using the certificates
Once the `cacerts` Kubernetes secret is created in the `istio-system` namespace, Istio automatically uses the custom CA certificate instead of the default self-signed certificate.
When you deploy applications to your Gloo Mesh service mesh, the workloads will receive leaf certificates signed by your Infisical PKI intermediate CA, enabling secure mTLS communication across your entire mesh infrastructure.
When you deploy applications to your Gloo Mesh service mesh, the workloads will receive leaf certificates signed by your Infisical intermediate CA, enabling secure mTLS communication across your entire mesh infrastructure.

7
docs/documentation/platform/pki/integration-guides/jboss-certbot.mdx
View File

@@ -1,9 +1,9 @@
---
title: "JBoss/WildFly"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on JBoss/WildFly with Certbot"
description: "Learn how to issue TLS certificates from Infisical using ACME enrollment on JBoss/WildFly with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [JBoss](https://www.jboss.org/)/[WildFly](https://wildfly.org/) application server.
This guide demonstrates how to use Infisical to issue TLS certificates for your [JBoss](https://www.jboss.org/)/[WildFly](https://wildfly.org/) application server.
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). JBoss/WildFly requires certificates in Java keystore format, which this guide addresses through the certificate conversion process.
@@ -223,4 +223,5 @@ Before you begin, make sure you have:
Certbot automatically renews certificates when they are within 30 days of expiration using its built-in systemd timer. The deploy hook above will run after each successful renewal, handling the keystore conversion and service restart automatically. Because JBoss/WildFly requires the standalone authenticator (which stops the service temporarily), plan for brief service interruptions during renewal.
</Note>
</Step>
</Steps>
</Steps>

4
docs/documentation/platform/pki/integration-guides/nginx-certbot.mdx
View File

@@ -1,9 +1,9 @@
---
title: "Nginx"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Nginx with Certbot"
description: "Learn how to issue TLS certificates from Infisical using ACME enrollment on Nginx with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Nginx](https://nginx.org/) server.
This guide demonstrates how to use Infisical to issue TLS certificates for your [Nginx](https://nginx.org/) server.
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles).

7
docs/documentation/platform/pki/integration-guides/tomcat-certbot.mdx
View File

@@ -1,9 +1,9 @@
---
title: "Tomcat"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Tomcat with Certbot"
description: "Learn how to issue TLS certificates from Infisical using ACME enrollment on Tomcat with Certbot"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Apache Tomcat](https://tomcat.apache.org/) application server.
This guide demonstrates how to use Infisical to issue TLS certificates for your [Apache Tomcat](https://tomcat.apache.org/) application server.
It uses [Certbot](https://certbot.eff.org/), an installable [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). Unlike web servers with native Certbot plugins, Tomcat requires certificates to be manually configured after issuance.
@@ -248,4 +248,5 @@ Before you begin, make sure you have:
Since Tomcat reads certificates from the file system on startup, you only need to restart the service after certificate renewal. The certificate file paths in `/etc/letsencrypt/live/` are symbolic links that automatically point to the latest certificates.
</Note>
</Step>
</Steps>
</Steps>

5
docs/documentation/platform/pki/integration-guides/windows-server-acme.mdx
View File

@@ -1,9 +1,9 @@
---
title: "Windows Server"
description: "Learn how to issue SSL/TLS certificates from Infisical using ACME enrollment on Windows Server with win-acme"
description: "Learn how to issue TLS certificates from Infisical using ACME enrollment on Windows Server with win-acme"
---
This guide demonstrates how to use Infisical to issue SSL/TLS certificates for your [Windows Server](https://www.microsoft.com/en-us/windows-server) environments.
This guide demonstrates how to use Infisical to issue TLS certificates for your [Windows Server](https://www.microsoft.com/en-us/windows-server) environments.
It uses [win-acme](https://www.win-acme.com/), a feature-rich [ACME](https://en.wikipedia.org/wiki/Automatic_Certificate_Management_Environment) client designed specifically for Windows, to request and renew certificates from Infisical using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). Win-acme offers excellent integration with IIS, Windows Certificate Store, and various certificate storage options.
@@ -191,4 +191,5 @@ Before you begin, make sure you have:
</Tab>
</Tabs>
</Step>
</Steps>

267
docs/documentation/platform/pki/k8s-cert-manager.mdx Normal file
View File

@@ -0,0 +1,267 @@
---
title: "Kubernetes cert-manager"
description: "Learn how to automatically provision and manage TLS certificates in Kubernetes using Infisical"
---
## Concept
This guide demonstrates how to use Infisical to issue TLS certificates back to your Kubernetes environment using [cert-manager](https://cert-manager.io/).
It uses the [ACME issuer type](https://cert-manager.io/docs/configuration/acme/) to request and renew certificates automatically from Infisical
using the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on a [certificate profile](/documentation/platform/pki/certificates/profiles). The issuer is perfect at obtaining X.509 certificates for Ingresses and other Kubernetes resources and can automatically renew them before expiration.
The typical workflow involves installing `cert-manager` and configuring resources that represent the connection details to Infisical as well as the certificates you want to issue.
Each issued certificate and its corresponding private key are stored in a Kubernetes `Secret`.
We recommend reading the official [cert-manager documentation](https://cert-manager.io/docs/) for a complete overview.
For the ACME-specific configuration, refer to the [ACME section](https://cert-manager.io/docs/configuration/acme/).
## Workflow
A typical workflow for using cert-manager with Infisical via ACME consists of the following steps:
1. Create a [certificate profile](/documentation/platform/pki/certificates/profiles) in Infisical with the [ACME enrollment method](/documentation/platform/pki/enrollment-methods/acme) configured on it.
2. Install `cert-manager` in your Kubernetes cluster.
3. Create a Kubernetes `Secret` containing the EAB (External Account Binding) credentials for the ACME certificate profile.
4. Create an `Issuer` or `ClusterIssuer` resource that connects to the desired Infisical [certificate profile](/documentation/platform/pki/certificates/profiles).
5. Create a `Certificate` resource defining the certificate you wish to issue and the target `Secret` where the certificate and private key will be stored.
6. Use the resulting Kubernetes `Secret` in your Ingresses or other resources.
## Guide
The following steps show how to install cert-manager (using `kubectl`) and obtain certificates from Infisical.
<Steps>
<Step title="Create a certificate profile with ACME as the enrollment method in Infisical">
Follow the instructions [here](/documentation/platform/pki/enrollment-methods/acme) to create a certificate profile that uses ACME enrollment.
After completion, you will have the following values:
- **ACME Directory URL**
- **EAB Key ID (KID)**
- **EAB Secret**
These will be needed in later steps.
<Note>
Currently, the Infisical ACME enrollment method only supports authentication via dedicated EAB credentials generated per certificate profile.
Support for [Kubernetes Auth](/documentation/platform/identities/kubernetes-auth) is planned for the near future.
</Note>
</Step>
<Step title="Install cert-manager">
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 apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.1/cert-manager.yaml
```
</Step>
<Step title="Create a Kubernetes Secret for the Infisical ACME EAB credentials">
Create a Kubernetes `Secret` that contains the **EAB Secret (HMAC key)** obtained in step 1.
The cert-manager uses this secret to authenticate with the Infisical ACME server.
<Tabs>
<Tab title="kubectl command">
```bash
kubectl create secret generic infisical-acme-eab-secret \
--namespace <namespace_you_want_to_issue_certificates_in> \
--from-literal=eabSecret=<eab_secret>
```
</Tab>
<Tab title="Configuration file">
```yaml acme-eab-secret.yaml
apiVersion: v1
kind: Secret
metadata:
name: infisical-acme-eab-secret
namespace: <namespace_you_want_to_issue_certificates_in>
data:
eabSecret: <eab_secret>
```
```bash
kubectl apply -f acme-eab-secret.yaml
```
</Tab>
</Tabs>
</Step>
<Step title="Create the cert-manager Issuer connecting to Infisical ACME server">
Next, create a cert-manager `Issuer` (or `ClusterIssuer`) by replacing the placeholders `<acme_server_url>`, `<your_email>`, and `<acme_eab_kid>` in the configuration below and applying it.
This resource configures cert-manager to use your Infisical PKI collection's ACME server for certificate issuance.
```yaml issuer-infisical.yaml
apiVersion: cert-manager.io/v1
kind: Issuer
metadata:
name: issuer-infisical
namespace: <namespace_you_want_to_issue_certificates_in>
spec:
acme:
# ACME server URL from your Infisical certificate profile (Step 1)
server: <acme_server_url>
# Email address for ACME account
# (any valid email works; currently ignored by Infisical)
email: <your_email>
externalAccountBinding:
# EAB Key ID from Step 1
keyID: <acme_eab_kid>
# Reference to the Kubernetes Secret containing the EAB
# HMAC key (created in Step 3)
keySecretRef:
name: infisical-acme-eab-secret
key: eabSecret
privateKeySecretRef:
name: issuer-infisical-account-key
solvers:
- http01:
ingress:
# Replace with your actual ingress class if different
className: nginx
```
```
kubectl apply -f issuer-infisical.yaml
```
You can check that the issuer was created successfully by running the following command:
```bash
kubectl get issuers.cert-manager.io -n <namespace_of_issuer> -o wide
```
```bash
NAME AGE
issuer-infisical 21h
```
<Note>
- Currently, the Infisical ACME server only supports the HTTP-01 challenge and requires successful challenge completion before issuing certificates. Support for optional challenges and DNS-01 is planned for a future release.
- An `Issuer` is namespace-scoped. Certificates can only be issued using an `Issuer` that exists in the same namespace as the `Certificate` resource.
- If you need to issue certificates across multiple namespaces with a single resource, create a `ClusterIssuer` instead. The configuration is identical except `kind: ClusterIssuer` and no `metadata.namespace`.
- More details: https://cert-manager.io/docs/configuration/acme/
</Note>
</Step>
<Step title="Create the Certificate">
Finally, request a certificate from Infisical ACME server by creating a cert-manager `Certificate` resource.
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: <namespace_you_want_to_issue_certificates_in>
spec:
dnsNames:
- certificate-by-issuer.example.com
# name of the resulting Kubernetes Secret
secretName: certificate-by-issuer
# total validity period of the certificate
duration: 48h
# cert-manager will attempt renewal 12 hours before expiry
renewBefore: 12h
privateKey:
algorithm: ECDSA
# uses NIST P-256 curve
size: 256
issuerRef:
name: issuer-infisical
```
The above sample configuration file specifies a certificate to be issued with the dns 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`.
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).
You can check that the certificate was created successfully by running the following command:
```bash
kubectl get certificates -n <namespace_of_your_certificate> -o wide
```
```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
```
</Step>
<Step title="Use Certificate in Kubernetes Secret">
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:
```bash
kubectl get secret certificate-by-issuer -n <namespace_of_your_certificate>
```
```bash
NAME TYPE DATA AGE
certificate-by-issuer kubernetes.io/tls 2 26h
```
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:
cert-manager.io/alt-names: certificate-by-issuer.example.com
cert-manager.io/ip-sans:
cert-manager.io/issuer-group: 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.
</Step>
</Steps>
## FAQ
<AccordionGroup>
<Accordion title="What fields can be configured on the Certificate resource?">
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).
<Note>
Currently, not all fields are supported by the Infisical PKI ACME server.
</Note>
</Accordion>
<Accordion title="Can certificates be renewed automatically?">
Yes. `cert-manager` will automatically renew certificates according to the `renewBefore` threshold of expiry as
specified in the corresponding `Certificate` resource.
You can read more about the `renewBefore` field [here](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.CertificateSpec).
</Accordion>
</AccordionGroup>

305
docs/documentation/platform/pki/pki-issuer.mdx
View File

@@ -1,305 +0,0 @@
---
title: "Kubernetes Issuer"
description: "Learn how to automatically provision and manage TLS certificates in Kubernetes using Infisical PKI"
---
## Concept
The Infisical PKI Issuer is an installable Kubernetes [cert-manager](https://cert-manager.io/) controller that uses Infisical PKI to sign certificate requests. The issuer is perfect for getting X.509 certificates for ingresses and other Kubernetes resources and capable of automatically renewing certificates as needed.
As part of the workflow, you install `cert-manager`, the Infisical PKI Issuer, and configure resources to represent the connection details to your Infisical PKI and the certificates you wish to issue. Each issued certificate and corresponding private key is made available in a Kubernetes secret.
We recommend reading the [cert-manager documentation](https://cert-manager.io/docs/) for a fuller understanding of all the moving parts.
## Workflow
A typical workflow for using the Infisical PKI Issuer to issue certificates for your Kubernetes resources consists of the following steps:
1. Creating a machine identity in Infisical.
2. Creating a Kubernetes secret to store the credentials of the machine identity.
3. Installing `cert-manager` into your Kubernetes cluster.
4. Installing the Infisical PKI Issuer controller into your Kubernetes cluster.
5. Creating an `Issuer` or `ClusterIssuer` resource in your Kubernetes cluster to represent the Infisical PKI issuer you wish to use.
6. Create the approver policy to accept certificate request.
7. Creating a `Certificate` resource in your Kubernetes cluster to represent a certificate you wish to issue. As part of this step, you specify the Kubernetes `Secret` to create and store the issued certificate and private key.
8. Consuming the issued certificate across your Kubernetes resources from the specified Kubernetes `Secret`.
## Guide
In the following steps, we explore how to install the Infisical PKI Issuer using [kubectl](https://github.com/kubernetes/kubectl) and use it to obtain certificates for your Kubernetes resources.
<Steps>
<Step title="Create an identity in Infisical">
Follow the instructions [here](/documentation/platform/identities/universal-auth) to configure a [machine identity](/documentation/platform/identities/machine-identities) in Infisical with Universal Auth.
By the end of this step, you should have a **Client ID** and **Client Secret** on hand as part of the Universal Auth configuration for the Infisical PKI Issuer to authenticate with Infisical; this will be useful in steps 4 and 5.
<Note>
Currently, the Infisical PKI Issuer only supports authenticating with Infisical via the [Universal Auth](/documentation/platform/identities/universal-auth) authentication method.
We're planning to add support for [Kubernetes Auth](/documentation/platform/identities/kubernetes-auth) in the near future.
</Note>
</Step>
<Step title="Install cert-manager">
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
```
</Step>
<Step title="Install the Issuer Controller">
Install the Infisical PKI Issuer controller into your Kubernetes cluster using one of the following methods:
<Tabs>
<Tab title="Helm">
```bash
helm repo add infisical-helm-charts 'https://dl.cloudsmith.io/public/infisical/helm-charts/helm/charts/'
helm install infisical-pki-issuer infisical-helm-charts/infisical-pki-issuer
```
</Tab>
<Tab title="kubectl">
```bash
kubectl apply -f https://raw.githubusercontent.com/Infisical/infisical-issuer/main/build/install.yaml
```
</Tab>
</Tabs>
</Step>
<Step title="Create Kubernetes Secret for Infisical PKI Issuer">
Start by creating a Kubernetes `Secret` containing the **Client Secret** from step 1. As mentioned previously, this will be used by the Infisical PKI issuer to authenticate with Infisical.
<Tabs>
<Tab title="kubectl command">
```bash
kubectl create secret generic issuer-infisical-client-secret \
--namespace <namespace_you_want_to_issue_certificates_in> \
--from-literal=clientSecret=<client_secret>
```
</Tab>
<Tab title="Configuration file">
```yaml secret-issuer.yaml
apiVersion: v1
kind: Secret
metadata:
name: issuer-infisical-client-secret
namespace: <namespace_you_want_to_issue_certificates_in>
data:
clientSecret: <client_secret>
```
```bash
kubectl apply -f secret-issuer.yaml
```
</Tab>
</Tabs>
</Step>
<Step title="Create Infisical PKI Issuer">
Next, create the Infisical PKI Issuer by filling out `url`, `clientId`, `projectId` or `certificateTemplateName`, 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: infisical-issuer.infisical.com/v1alpha1
kind: Issuer
metadata:
name: issuer-infisical
namespace: <namespace_you_want_to_issue_certificates_in>
spec:
url: "https://app.infisical.com" # the URL of your Infisical instance
projectId: <project_id> # the ID of the project you want to use to issue certificates
certificateTemplateName: <certificate_template_name> # the name of the certificate template you want to use to issue certificates against
authentication:
universalAuth:
clientId: <client_id> # the Client ID from step 1
secretRef: # reference to the Secret created in step 4
name: "issuer-infisical-client-secret"
key: "clientSecret"
```
```
kubectl apply -f infisical-issuer.yaml
```
You can check that the issuer was created successfully by running the following command:
```bash
kubectl get issuers.infisical-issuer.infisical.com -n <namespace_of_issuer> -o wide
```
```bash
NAME AGE
issuer-infisical 21h
```
<Note>
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/).
</Note>
</Step>
<Step title="Create Approver Policy">
If you create a `CertificateRequest` now, you'll notice it's neither approved nor denied. This is expected because by default cert-manager approver controller requires an approver-policy.
To enable approval, create the following YAML file and apply it:
```yaml infisical-approver-policy.yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: infisical-issuer-approver
rules:
# Permission to approve or deny CertificateRequests for signers in cert-manager.io API group
- apiGroups: ['cert-manager.io']
resources: ['signers']
verbs: ['approve']
resourceNames:
# Grant approval permissions for namespaced issuers
- "issuers.infisical-issuer.infisical.com/default.issuer-infisical"
# Grant approval permissions for cluster-scoped issuers
- "clusterissuers.infisical-issuer.infisical.com/clusterissuer-infisical"
---
# Bind the cert-manager service account to the new role
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: infisical-issuer-approver-binding
subjects:
- kind: ServiceAccount
name: cert-manager
namespace: cert-manager
roleRef:
apiGroup: rbac.authorization.k8s.io
kind: ClusterRole
name: infisical-issuer-approver
```
```
kubectl apply -f infisical-approver-policy.yaml
```
This configuration creates a `ClusterRole` named `infisical-issuer-approver` that grants approval permissions for specific Infisical issuer types. It then binds this role to the cert-manager service account, allowing it to approve certificate requests from your Infisical issuers.
For information, check out [cert manager approval policy doc](https://cert-manager.io/docs/policy/approval/approver-policy/).
</Step>
<Step title="Create Certificate">
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: <namespace_you_want_to_issue_certificates_in>
spec:
commonName: certificate-by-issuer.example.com # the common name for the certificate
secretName: certificate-by-issuer # the name of the Kubernetes Secret to create and store the certificate and private key in
issuerRef:
name: issuer-infisical
group: infisical-issuer.infisical.com
kind: Issuer
privateKey: # the algorithm and key size to use
algorithm: ECDSA
size: 256
duration: 48h # the ttl for the certificate
renewBefore: 12h # the time before the certificate expiry that the certificate should be automatically renewed
```
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`.
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).
You can check that the certificate was created successfully by running the following command:
```bash
kubectl get certificates -n <namespace_of_your_certificate> -o wide
```
```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
```
</Step>
<Step title="Use Certificate in Kubernetes Secret">
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:
```bash
kubectl get secret certificate-by-issuer -n <namespace_of_your_certificate>
```
```bash
NAME TYPE DATA AGE
certificate-by-issuer kubernetes.io/tls 2 26h
```
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: infisical-issuer.infisical.com
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.
</Step>
</Steps>
## FAQ
<AccordionGroup>
<Accordion title="What fields can be configured on the Certificate resource?">
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).
<Note>
Currently, not all fields are supported by the Infisical PKI Issuer.
</Note>
</Accordion>
<Accordion title="Can certificates be renewed automatically?">
Yes. `cert-manager` will automatically renew certificates according to the `renewBefore` threshold of expiry as
specified in the corresponding `Certificate` resource.
You can read more about the `renewBefore` field [here](https://cert-manager.io/docs/reference/api-docs/#cert-manager.io/v1.CertificateSpec).
</Accordion>
<Accordion title="Why is my CertificateRequest not being approved, showing 'CertificateRequest has not been approved yet. Ignoring.'?">
If you see log messages similar to:
```
"CertificateRequest has not been approved yet. Ignoring.","controller":"certificaterequest","controllerGroup":"cert-manager.io","controllerKind":"CertificateRequest","CertificateRequest":{"name":"skynet-infisical-rta-rsa2048-1","namespace":"infisical-system"},"namespace":"infisical-system","name":"skynet-infisical-rta-rsa2048-1","reconcileID":"bfb7cad9-d867-45b5-b3a3-0139e731b7a6"}
```
This indicates that the `CertificateRequest` has been created, but `cert-manager` has not yet approved it. This typically occurs because a necessary approver policy is missing. Refer to the documentation above to create an approver policy.
</Accordion>
</AccordionGroup>