Certificate management
...
Post-integration tasks
Validate and test
11 min
if there are issues, visit docid\ zi flu lbtsabrl65dr3h to view different troubleshooting solutions files needed for each test there are 3 files that need to be applied to each integration test secret yml this secret stores the {{ch}} integration specific partition/application's api key for use by the futurex issuer to authenticate to {{ch}} 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 {{ch}} platform it tells cert manager exactly how to authenticate to and communicate with {{ch}} 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 apiversion v1 kind secret metadata 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 apiversion certificate k8s futurex com/v1 kind cryptohubissuer metadata 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 apiversion cert manager io/v1 kind certificate metadata 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 minikube this section will validate the kubernetes cert manager integration with {{ch}} by setting up the files needed for cert manager to establish communication with {{ch}} , send a certificate signing request (csr), and, once approved, retrieve the signed csr from the {{ch}} secret yml apiversion v1 kind secret metadata 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 apiversion certificate k8s futurex com/v1 kind cryptohubissuer metadata 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 apiversion cert manager io/v1 kind certificate metadata 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 validation steps using the files create a custom namespace for the secret , cryptohubissuer , and certificate kubectl create namespace ch cert manager 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 secret yml apiversion v1 kind secret metadata name ch hsm credentials namespace ch cert manager stringdata apikey "acy5m3vjttc3wr36pe bnod4jpqngdwgbr527wjoya2qqtxteqaa4mbusy4ab56 izcguwvqte6g6ca" issuer yml apiversion certificate k8s futurex com/v1 kind cryptohubissuer metadata name cryptohub issuer namespace ch cert manager spec uri "https //10 40 20 10/" policyid "01d5bf1d bcad 0000 0000 ebb402480751" apikeysecret "ch hsm credentials" extensionprofile "tls certificate" hashtype "sha 256" insecureskipverify true # needed for internal futurex testing (can remove if posting) \# debug true cert yml apiversion cert manager io/v1 kind certificate metadata name example com namespace ch cert manager spec secretname ch hsm credential duration 2160h renewbefore 360h isca false commonname example com privatekey algorithm rsa encoding pkcs1 size 2048 usages \ server auth \ client auth subject organizations \ cert manager dnsnames \ example com \ www example com uris \ spiffe //cluster local/ns/sandbox/sa/example ipaddresses \ 192 168 0 5 issuerref name cryptohub issuer kind cryptohubissuer group certificate k8s futurex com 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 secret issuer certificate kubectl apply f secret yml kubectl apply f issuer yml kubectl apply f cert yml if no errors arose, a csr should automatically be created, ready to be signed to check, run the following command 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 name approved denied ready issuer requester age example com 1 cryptohub issuer system\ serviceaccount\ cert manager\ cert manager 3m24s 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 cmctl approve example com 1 n ch cert manager login to {{ch}} 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 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 kubectl describe certificaterequest n ch cert manager a positive output should look something similar to below 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 the validation prcoess can be repeated with the second futurex issuer type cryptohubclusterissuer this is done by editing kind in issuer yml kind in cert yml , under issuerref microk8s validation steps using the files create a custom namespace for the secret , cryptohubissuer , and certificate microk8s kubectl create namespace ch cert manager 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 secret yml apiversion v1 kind secret metadata name ch hsm credentials namespace ch cert manager stringdata apikey "asq hlzgex7p3aldwn2jocgg4goo rabpceniafbizr3p7bteqaa4mbuszleu57esx1neuek1pmwih4" issuer yml apiversion certificate k8s futurex com/v1 kind cryptohubissuer metadata name cryptohub issuer namespace ch cert manager spec uri "https //10 40 20 10/" policyid "01d5bf1d bcad 0000 0000 ebb402480751" apikeysecret "ch hsm credentials" extensionprofile "tls certificate" hashtype "sha 256" insecureskipverify true # needed for internal futurex testing (can remove if posting) \# debug true cert yml apiversion cert manager io/v1 kind certificate metadata name example com namespace ch cert manager spec secretname ch hsm credential duration 2160h renewbefore 360h isca false commonname example com privatekey algorithm rsa encoding pkcs1 size 2048 usages \ server auth \ client auth subject organizations \ cert manager dnsnames \ example com \ www example com uris \ spiffe //cluster local/ns/sandbox/sa/example ipaddresses \ 192 168 0 5 issuerref name cryptohub issuer kind cryptohubissuer group certificate k8s futurex com 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 secret issuer certificate microk8s kubectl apply f secret yml microk8s kubectl apply f issuer yml microk8s kubectl apply f cert yml if no errors arose, a csr should automatically be created, ready to be signed to check, run the following command 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 name approved denied ready issuer requester age example com 1 cryptohub issuer system\ serviceaccount\ cert manager\ cert manager 3m24s login to {{ch}} with the approate 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 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 microk8s kubectl describe certificaterequest n ch cert manager a positive output should look something similar to below 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 the validation prcoess can be repeated with the second futurex issuer type cryptohubclusterissuer this is done by editing kind in issuer yml kind in cert yml , under issuerref k3s single device (docker) validation steps using the files create a custom namespace for the secret , cryptohubissuer , and certificate kubectl create namespace ch cert manager 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 secret yml apiversion v1 kind secret metadata name ch hsm credentials namespace ch cert manager stringdata apikey "acy5m3vjttc3wr36pe bnod4jpqngdwgbr527wjoya2qqtxteqaa4mbusy4ab56 izcguwvqte6g6ca" issuer yml apiversion certificate k8s futurex com/v1 kind cryptohubissuer metadata name cryptohub issuer namespace ch cert manager spec uri "https //10 40 20 10/" policyid "01d5bf1d bcad 0000 0000 ebb402480751" apikeysecret "ch hsm credentials" extensionprofile "tls certificate" hashtype "sha 256" insecureskipverify true # needed for internal futurex testing (can remove if posting) \# debug true 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 secret issuer kubectl apply f secret yml kubectl apply f issuer yml copy the k3s yaml file that was created in the docid 1iz60eia0gtdvphdsyn6l page to the agent's filesystem docker cp /k3s yaml k3s agent 1 / create a terminal session for the agent docker exec it k3s agent 1 sh 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 vi k3s yaml the server's docker hostname can be used server https //k3s server 6443 on the k3s agent 1 terminal session, update the kubectl environment variable for the agent export kubeconfig=k3s yaml 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 vi cert ymlapiversion cert manager io/v1 kind certificate metadata name example com namespace ch cert manager spec secretname ch hsm credential duration 2160h renewbefore 360h isca false commonname example com privatekey algorithm rsa encoding pkcs1 size 2048 usages \ server auth \ client auth subject organizations \ cert manager dnsnames \ example com \ www example com uris \ spiffe //cluster local/ns/sandbox/sa/example ipaddresses \ 192 168 0 5 issuerref name cryptohub issuer kind cryptohubissuer group certificate k8s futurex com on the k3s agent 1 terminal session, apply the certificate using kubectl kubectl apply f cert yml 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 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 name approved denied ready issuer requester age example com 1 cryptohub issuer system\ serviceaccount\ cert manager\ cert manager 3m24s approve the request using cmctl so that kubernetes api can send the certificate over to {{ch}} 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 name approved denied ready issuer requester age example com 1 true false cryptohub issuer system\ serviceaccount\ cert manager\ cert manager 5m23s login into {{ch}} with the approate 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 to validate if the signed certificate was received, on the k3s server run kubectl describe certificaterequest n ch cert manager example com 1 a positive output should look something similar to below 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 the validation prcoess can be repeated with the second futurex issuer type cryptohubclusterissuer this is done by editing kind in issuer yml kind in cert yml , under issuerref k3s multidevice validation steps using the files create a custom namespace for the secret , cryptohubissuer , and certificate kubectl create namespace ch cert manager 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 secret yml apiversion v1 kind secret metadata name ch hsm credentials namespace ch cert manager stringdata apikey "acy5m3vjttc3wr36pe bnod4jpqngdwgbr527wjoya2qqtxteqaa4mbusy4ab56 izcguwvqte6g6ca" issuer yml apiversion certificate k8s futurex com/v1 kind cryptohubissuer metadata name cryptohub issuer namespace ch cert manager spec uri "https //10 40 20 10/" policyid "01d5bf1d bcad 0000 0000 ebb402480751" apikeysecret "ch hsm credentials" extensionprofile "tls certificate" hashtype "sha 256" insecureskipverify true # needed for internal futurex testing (can remove if posting) \# debug true 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 secret issuer kubectl apply f secret yml kubectl apply f issuer yml copy the k3s yaml from the server machine to the worker machine the example below uses secure copy, scp scp /path/to/k3s yaml \<worker user> \<worker ip> /path/to/copy/to 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 vi k3s yamlserver https //\<server hostname or ip> 6443 on the worker machine, update the kubectl environment variable export kubeconfig=k3s yaml 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 vi cert ymlapiversion cert manager io/v1 kind certificate metadata name example com namespace ch cert manager spec secretname ch hsm credential duration 2160h renewbefore 360h isca false commonname example com privatekey algorithm rsa encoding pkcs1 size 2048 usages \ server auth \ client auth subject organizations \ cert manager dnsnames \ example com \ www example com uris \ spiffe //cluster local/ns/sandbox/sa/example ipaddresses \ 192 168 0 5 issuerref name cryptohub issuer kind cryptohubissuer group certificate k8s futurex com on the worker machine, apply the certificate using kubectl on the worker machine kubectl apply f cert yml 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 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 name approved denied ready issuer requester age example com 1 cryptohub issuer system\ serviceaccount\ cert manager\ cert manager 3m24s on the server mahcine, approve the request using cmctl so that kubernetes api can send the certificate over to {{ch}} 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 name approved denied ready issuer requester age example com 1 true false cryptohub issuer system\ serviceaccount\ cert manager\ cert manager 5m23s login into {{ch}} with the approate 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 to validate if the signed certificate was received, on the server machine run microk8s kubectl describe certificaterequest n ch cert manager a positive output should look something similar to below 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 the validation prcoess can be repeated with the second futurex issuer type cryptohubclusterissuer this is done by editing kind in issuer yml kind in cert yml , under issuerref