There are 3 files that need to be applied to each integration test:-Secret.yml
This secret stores the CryptoHub integration-specific partition/application’s API Key for use by the Futurex issuer to authenticate to CryptoHub. The partition/application must have the permission to upload a CSR and access the issuer policy.
Issuer.yml
A Kubernetes Custom Resource Definition (CRD) configuration file that defines a CryptohubIssuer or CryptohubClusterIssuer.
Its primary function is to establish a bridge between the Kubernetes cert-manager add-on and the Futurex CryptoHub platform. It tells cert-manager exactly how to authenticate to and communicate with CryptoHub to request and issue trusted X.509 TLS certificates.
Cert.yml
A file describes the desired properties of a new certificate, triggering the internal generation of a CSR. In the cert-manager ecosystem, the file typically defines a Kubernetes Certificate resource.
The files pasted below are to be used as a template.
For the namespace, the cert.yml, issuer.yml, and secret.yml must be in the same namespace.
Names of Kubernetes resources strictly follow DNS Label Naming (RFC 1035).
Secret.yml
YAML
apiVersion: v1kind: Secretmetadata: name: <secret-name> # The name applications and other YAML files use to find this Secret. namespace: <custom-namespace> # Namespace where this resource (e.g., Secret or Issuer) will be created.stringData: apikey: "<partition_api_key>" # API key of the partition / role specific for this integration
Issuer.yml
YAML
apiVersion: certificate.k8s.futurex.com/v1kind: CryptohubIssuermetadata: name: <issuer-name> # Specify the name applications and other YAML files use to reference this issuer. namespace: <custom-namespace> # Namespace where this resource (e.g., Secret or Issuer) will be created.spec: uri: "<ip-of-CryptoHub>" # The IP address or hostname of Cryptohub policyId: "<issuance-policy-id>" # On CryptoHub, after right clicking the CA > Issuance Policy > Edit..., copy the UUID here. apiKeySecret: "<secret-name>" # The name of the secret found in Secret.yml extensionProfile: "TLS Certificate" hashType: "SHA-256" # debug: true
Cert.yml
YAML
apiVersion: cert-manager.io/v1kind: Certificatemetadata: name: example-com # The name of this Certificate resource. namespace: <custom-namespace> # Namespace where this Certificate resource will be created.spec: secretName: <secret-name> # The name of the secret found in Secret.yml # --- Certificate Lifetime Settings --- duration: 2160h # Requested total lifespan of the certificate (e.g., 90 days). renewBefore: 360h # How long before expiry (15 days) cert-manager should start renewal. isCA: false # Set to 'true' if the resulting certificate should be a CA certificate. commonName: example.com # Deprecated: The main subject name. Preferred method is 'dnsNames'. # --- Private Key Configuration --- privateKey: algorithm: RSA encoding: PKCS1 size: 2048 # The size of the private key. usages: - server auth # Allows the certificate to be used for TLS servers (e.g., Ingress). - client auth # Allows the certificate to be used for client authentication. # --- Certificate Subject Details --- subject: organizations: - cert-manager dnsNames: - example.com # Primary DNS Subject Alternative Name (SAN). - www.example.com # Additional DNS SAN. # Non-DNS SANs (optional) uris: - spiffe://cluster.local/ns/sandbox/sa/example ipAddresses: - 192.168.0.5 # --- Issuer Reference (MANDATORY for Futurex Integration) --- issuerRef: name: <issuer-name> # Must match the name found in Issuer.yml. kind: <fx-crd-kind> # Must be the Kind defined by the Futurex Custom Resource (CRD). Either CryptohubIssuer or CryptohubClusterIssuer. group: certificate.k8s.futurex.com # The API Group defined by the Futurex CRD.
This section will validate the Kubernetes cert-manager integration with CryptoHub by setting up the files needed for cert-manager to establish communication with CryptoHub, send a certificate signing request (CSR), and, once approved, retrieve the signed CSR from the CryptoHub.Secret.yml
YAML
apiVersion: v1kind: Secretmetadata: name: <secret-name> # The name applications and other YAML files use to find this Secret. namespace: <custom-namespace> # Namespace where this resource (e.g., Secret or Issuer) will be created.stringData: apikey: "<partition_api_key>" # API key of the partition / role specific for this integration
Issuer.yml
YAML
apiVersion: certificate.k8s.futurex.com/v1kind: CryptohubIssuermetadata: name: <issuer-name> # Specify the name applications and other YAML files use to reference this issuer. namespace: <custom-namespace> # Namespace where this resource (e.g., Secret or Issuer) will be created.spec: uri: "<ip-of-CryptoHub>" # The IP address or hostname of Cryptohub policyId: "<issuance-policy-id>" # On CryptoHub, after right clicking the CA > Issuance Policy > Edit..., copy the UUID here. apiKeySecret: "<secret-name>" # The name of the secret found in Secret.yml extensionProfile: "TLS Certificate" hashType: "SHA-256" # debug: true
Cert.yml
YAML
apiVersion: cert-manager.io/v1kind: Certificatemetadata: name: example-com # The name of this Certificate resource. namespace: <custom-namespace> # Namespace where this Certificate resource will be created.spec: secretName: <secret-name> # The name of the secret found in Secret.yml # --- Certificate Lifetime Settings --- duration: 2160h # Requested total lifespan of the certificate (e.g., 90 days). renewBefore: 360h # How long before expiry (15 days) cert-manager should start renewal. isCA: false # Set to 'true' if the resulting certificate should be a CA certificate. commonName: example.com # Deprecated: The main subject name. Preferred method is 'dnsNames'. # --- Private Key Configuration --- privateKey: algorithm: RSA encoding: PKCS1 size: 2048 # The size of the private key. usages: - server auth # Allows the certificate to be used for TLS servers (e.g., Ingress). - client auth # Allows the certificate to be used for client authentication. # --- Certificate Subject Details --- subject: organizations: - cert-manager dnsNames: - example.com # Primary DNS Subject Alternative Name (SAN). - www.example.com # Additional DNS SAN. # Non-DNS SANs (optional) uris: - spiffe://cluster.local/ns/sandbox/sa/example ipAddresses: - 192.168.0.5 # --- Issuer Reference (MANDATORY for Futurex Integration) --- issuerRef: name: <issuer-name> # Must match the name found in Issuer.yml. kind: <fx-crd-kind> # Must be the Kind defined by the Futurex Custom Resource (CRD). Either CryptohubIssuer or CryptohubClusterIssuer. group: certificate.k8s.futurex.com # The API Group defined by the Futurex CRD.
Create a custom namespace for the Secret, CryptohubIssuer, and Certificate.
Shell
kubectl create namespace ch-cert-manager
2
Copy and paste the contents in the templates above into appropriately named files, and edit the files to match the values for your specific use case using a tool like nano or vim.
For this specific validation, the following files contains information to serve as an example:
Apply the files to create the Kubernetes resources.
The order of how the files are applied matters. The resources need to be created / updated in a specific sequence so that the cert-manager controller can successfully process them.The order is:
If no errors arose, a CSR should automatically be created, ready to be signed. To check, run the following command:
Shell
kubectl get certificaterequest -n ch-cert-manager
The -n flag value should be the namespace that you have created.
Successful output should like similar to:
None
NAME APPROVED DENIED READY ISSUER REQUESTER AGEexample-com-1 cryptohub-issuer system:serviceaccount:cert-manager:cert-manager 3m24s
5
Use cmctl to approve the CSR. This will let the cert-manager controller that the request is valid and should proceed to be signed by the assigned issuer.
Shell
cmctl approve example-com-1 -n ch-cert-manager
6
Login to CryptoHub with the appropriate identity that has the permission to sign the CSR.
Go to PKI and CA > PKI Signing Approvals.
Click on the + icon next to the approval group created for this integration.
A new entry will appear, displaying the yellow paper with a pen, and a status column showing “Pending 0/x”. The value ‘x’ indicates the total number of required approvals or identities that must approve the CSR before the signed certificate is issued.
To view the details of the CSR, right-click it and select Edit.
To approve or deny the CSR, either select the CSR and click on Approve or Deny on the bottom right or right-click on the CSR and select Approve or Deny.
After approving the CSR, a box will appear describing the User that signed the CSR, the Status of the CSR, the Time that it was signed, and a Message box that the user can use to write an optional message.
Select [ OK ] for the approval to be issued.
7
To validate if the signed certificate was received, go the terminal where Minikube was installed, and with the name of the CertificateRequest that was discovered earlier, run the command to find details about the approval process.
A positive output should look something similar to below:
None
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning RetryableError 11m cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: updated request id annotation Warning RetryableError 6m55s (x253 over 11m) cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: pending approval Normal Issued 3m8s cryptohubissuer.k8s.futurex.com Succeeded signing the CertificateRequest
8
The validation process can be repeated with the second Futurex issuer type: CryptohubClusterIssuerThis is done by editing:
Create a custom namespace for the Secret, CryptohubIssuer, and Certificate
Shell
microk8s kubectl create namespace ch-cert-manager
2
Copy and paste the contents in the templates above into appropiately named files, and edit the files to match the values for your specific use case using a tool like nano or vim.
For this specific validation, the following files contains information to serve as an example:
Apply the files to create the Kubernetes resources.
The order of how the files are applied matters. The resources need to be created / updated in a specific sequence so that the cert-manager controller can successfully process them.The order is:
If no errors arose, a CSR should automatically be created, ready to be signed. To check, run the following command:
Shell
microk8s kubectl get certificaterequest -n ch-cert-manager
The -n flag value should be the namespace that you have created.
Successful output should like similar to:
None
NAME APPROVED DENIED READY ISSUER REQUESTER AGEexample-com-1 cryptohub-issuer system:serviceaccount:cert-manager:cert-manager 3m24s
5
Login to CryptoHub with the appropriate identity that has the permission to sign the CSR.
Go to PKI and CA > PKI Signing Approvals.
Click on the + icon next to the approval group created for this integration.
A new entry will appear, displaying the yellow paper with a pen, and a status column showing “Pending 0/x”. The value ‘x’ indicates the total number of required approvals or identities that must approve the CSR before the signed certificate is issued.
To view the details of the CSR, right-click it and select Edit.
To approve or deny the CSR, either select the CSR and click on Approve or Deny on the bottom right or right-click on the CSR and select Approve or Deny.
After approving the CSR, a box will appear describing the User that signed the CSR, the Status of the CSR, the Time that it was signed, and a Message box that the user can use to write an optional message.
Select [ OK ] for the approval to be issued.
6
To validate if the signed certificate was received, go the terminal where Minikube was installed, and with the name of the CertificateRequest that was discovered earlier, run the command to find details about the approval process
A positive output should look something similar to below:
None
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning RetryableError 11m cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: updated request id annotation Warning RetryableError 6m55s (x253 over 11m) cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: pending approval Normal Issued 3m8s cryptohubissuer.k8s.futurex.com Succeeded signing the CertificateRequest
7
The validation process can be repeated with the second Futurex issuer type: CryptohubClusterIssuerThis is done by editing:
Create a custom namespace for the Secret, CryptohubIssuer, and Certificate.
Shell
kubectl create namespace ch-cert-manager
2
On the machine hosting the k3s-server, copy and paste the contents in the templates above into appropiately named files, and edit the files to match the values for your specific use case using a tool like nano or vim.
For this specific validation, the following files contains information to serve as an example
Apply the files to create the Kubernetes resources.
The order of how the files are applied matters. The resources need to be created / updated in a specific sequence so that the cert-manager controller can successfully process them.The order is:
Copy the k3s.yaml file that was created in the Install the Kubernetes tool page to the agent’s filesystem.
Shell
docker cp ./k3s.yaml k3s-agent-1:/
5
Create a terminal session for the agent.
Shell
docker exec -it k3s-agent-1 sh
6
On the k3s-agent-1 terminal session, edit the k3s.yaml file to change the hostname of the server from 127.0.0.1 or whatever the default value is to the given server hostname or server IP address.
Shell
vi k3s.yaml
The server’s Docker hostname can be used.
None
server: https://k3s-server:6443
7
On the k3s-agent-1 terminal session, update the kubectl environment variable for the agent.
Shell
export KUBECONFIG=k3s.yaml
8
On the k3s-agent-1 terminal session, copy and paste the contents in the cert template above into an appropriately named file (e.g., Cert.yml) , and edit the files to match the values for your specific use case using vi tool.
For this specific validation, the following file contains information to serve as an example.
On the k3s-agent-1 terminal session, apply the certificate using kubectl:
Shell
kubectl apply -f cert.yml
10
A CSR should automatically be created, ready to be approved by cmctl. On a terminal connected to k3s-server, run the following command to check if the CSR was generated:
Shell
kubectl get certificaterequest -n ch-cert-manager example-com-1
The -n flag value should be the namespace that you have created.
Successful output should like similar to:
None
NAME APPROVED DENIED READY ISSUER REQUESTER AGEexample-com-1 cryptohub-issuer system:serviceaccount:cert-manager:cert-manager 3m24s
11
Approve the request using cmctl so that Kubernetes API can send the certificate over to CryptoHub.
Shell
cmctl approve -n ch-cert-manager example-com-1
Rerun the get certificaterequest command and the APPROVED column should be updated to True, and READY to False
Login into CryptoHub with the appropriate identity that has the permission to sign the CSR.
Go to PKI and CA > PKI Signing Approvals.
Click on the + icon next to the approval group created for this integration.
A new entry will appear, displaying the yellow paper with a pen, and a status column showing “Pending 0/x”. The value ‘x’ indicates the total number of required approvals or identities that must approve the CSR before the signed certificate is issued.
To view the details of the CSR, right-click it and select Edit.
To approve or deny the CSR, either select the CSR and click on Approve or Deny on the bottom right or right-click on the CSR and select Approve or Deny.
After approving the CSR, a box will appear describing the User that signed the CSR, the Status of the CSR, the Time that it was signed, and a Message box that the user can use to write an optional message.
Select [ OK ] for the approval to be issued.
13
To validate if the signed certificate was received, on the k3s-server run:
A positive output should look something similar to below:
None
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning RetryableError 11m cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: updated request id annotation Warning RetryableError 6m55s (x253 over 11m) cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: pending approval Normal Issued 3m8s cryptohubissuer.k8s.futurex.com Succeeded signing the CertificateRequest
14
The validation process can be repeated with the second Futurex issuer type: CryptohubClusterIssuerThis is done by editing:
Create a custom namespace for the Secret, CryptohubIssuer, and Certificate.
Shell
kubectl create namespace ch-cert-manager
2
On the server machine, copy and paste the contents in the templates above into appropiately named files, and edit the files to match the values for your specific use case using a tool like nano or vim.
For this specific validation, the following files contains information to serve as an example
Apply the files to create the Kubernetes resources.
Important: The order of how the files are applied matters. The resources need to be created / updated in a specific sequence so that the cert-manager controller can successfully process them.The order is:
Edit the k3s.yaml file on the worker machine to change the hostname of the server from the default value to the the server hostname or server IP address.
Shell
vi k3s.yaml
None
server: https://<Server_Hostname_Or_IP>:6443
6
On the worker machine, update the kubectl environment variable
Shell
export KUBECONFIG=k3s.yaml
7
On the worker machine, copy and paste the contents in the cert template above into an appropriately named file (e.g., Cert.yml) , and edit the files to match the values for your specific use case using vi tool.For this specific validation, the following file contains information to serve as an example:
On the worker machine, apply the certificate using kubectl on the worker machine:
Shell
kubectl apply -f cert.yml
9
A CSR should automatically be created, ready to be approved by cmctl. On the server machine, run the following command to check if the CSR was generated:
Shell
kubectl get certificaterequest -n ch-cert-manager example-com-1
The -n flag value should be the namespace that you have created.
Successful output should like similar to:
None
NAME APPROVED DENIED READY ISSUER REQUESTER AGEexample-com-1 cryptohub-issuer system:serviceaccount:cert-manager:cert-manager 3m24s
10
On the server mahcine, approve the request using cmctl so that Kubernetes API can send the certificate over to CryptoHub.
Shell
cmctl approve -n ch-cert-manager example-com-1
Rerun the get certificaterequest command and the APPROVED column should be updated to True, and READY to False
Login into CryptoHub with the appropriate identity that has the permission to sign the CSR.
Go to PKI and CA > PKI Signing Approvals.
Click on the + icon next to the approval group created for this integration.
A new entry will appear, displaying the yellow paper with a pen, and a status column showing “Pending 0/x”. The value ‘x’ indicates the total number of required approvals or identities that must approve the CSR before the signed certificate is issued.
To view the details of the CSR, right-click it and select Edit.
To approve or deny the CSR, either select the CSR and click on Approve or Deny on the bottom right or right-click on the CSR and select Approve or Deny.
After approving the CSR, a box will appear describing the User that signed the CSR, the Status of the CSR, the Time that it was signed, and a Message box that the user can use to write an optional message.
Select [ OK ] for the approval to be issued.
12
To validate if the signed certificate was received, on the server machine run
A positive output should look something similar to below:
None
Events: Type Reason Age From Message ---- ------ ---- ---- ------- Warning RetryableError 11m cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: updated request id annotation Warning RetryableError 6m55s (x253 over 11m) cryptohubissuer.k8s.futurex.com Signing still in progress. Reason: Signing still in progress. Reason: pending approval Normal Issued 3m8s cryptohubissuer.k8s.futurex.com Succeeded signing the CertificateRequest
13
The validation process can be repeated with the second Futurex issuer type: CryptohubClusterIssuerThis is done by editing:
