Building and Deploying External Issuer For Certificate Management - Support and Troubleshooting

Building and Deploying External Issuer For Certificate Management Build External Issuer Docker Image

Deploy Containerised external issuer by creating a Docker image with the provided recipes.

Procedure:

Download the External Issuer Docker recipe ZIP file from the External Issuer download page. Unzip the ZIP file to a folder. (Optional) You can change the current directory to the new folder. To build an image, run the build command: docker build [--tag ] For more information on the build command, see the Docker build command documentation .The path to the docker recipe can be a relative path or simply a dot (.) if the recipe folder is the current directory. Setting an image tag is optional but recommended. The build command takes the following build arguments:

INSTALLATION_URL : This parameter gives the link to download the binary file. By default, it is set to the download link for the external issuer binary file provided on external issuer download page.

INSTALLATION_FILE : This parameter gives the name of local External Issuer Binary file. The default value is empty. If this parameter is not empty, the recipe will use the local file instead of downloading from remote. Please note that this parameter is supposed to give the file name only, not the full path. Before the build, the local file needs to be copied to the asset subfolder of the recipe folder.

Deploying External Issuer in Kubernetes Cluster:

Prerequisites:

cert-mananger installed in the kubernetes cluster Certificate Management application installed on ServiceNow instance and configured to route certificate requests to the relevant Certificate Authority. (Verify it is working correctly by submitting a request manually using the catalog) ServiceNow user with roles: sn_disco_certmgmt.pki_admin / sn_disco_certmgmt.pki_user Deploy using Helm:

Download the External Issuer Helm Chart ZIP file from the External Issuer download page. Unzip the ZIP file to a folder Configure the required values in the values.yaml file according to your environment and requirements. You can also use the --set flag to override values in the values.yaml file. Here's a breakdown of the available options: instance : Replace the values for url with your ServiceNow instance details. b. certificateDetails : Specify the details for the requested certificates. Set the certificateEnvironment to the desired environment (e.g., "development"), certificatePurpose to the purpose of the certificates (e.g., "internal"), validityPeriod to the default validity period in days (e.g., "365"), certificateOwnerGroupSysId and certificateOwnerSysId to the respective SysIds if applicable. Update taskRetryInterval (in Minutes) if you want to change the polling period of external issuer to poll the state of task at different time interval. Lower value will mean external issuer will check the state of the task more frequently c. image : Update the repository with the details of the Docker image built from the Docker recipe. You can also modify the pullPolicy and tag if needed. d. imagePullSecrets : If you require any image pull secrets, specify them here. e. nameOverride and fullnameOverride: If you want to override the name and fullname of the Helm release, provide the desired values. f. resources : Adjust the resource limits and requests based on your environment and requirements. Modify the values for cpu and memory under limits and requests as necessary. Open a command prompt or terminal and navigate to the directory where the Helm chart is located. Run the following command to install the Helm chart, replacing with the desired name for the Helm release and with the path to the Helm chart directory If you are editing the existing values.yaml file, use the following command. Use the --create-namespace tag to create a new namespace. Example: helm install --namespace --create-namespace If you want to pass the values as command-line arguments, use the following command. Example: helm install --set key1=value1,key2=value2 --namespace If you have a custom-values.yaml file, you can use the following command. Example: helm install -f custom-values.yaml --namespace Create a secret for ServiceNow User using the below command kubectl create secret generic clusterissuer-servicenow-credentials --from-literal=user= --from-literal=password= -n Note: Secret should be in same namespace as your deployment Wait for the installation process to complete. You can check the status of the release using the helm status command. Once the installation is successful, the external issuer should be deployed in your Kubernetes environment according to the provided configuration. Make sure to validate the deployed resources and adjust any additional settings or configurations as needed for your specific use case.

Note: If you have created the image in a private repository, you should create a secret for the private repository and add the secret in imagePullSecrets as shown below imagePullSecrets: [ { name: "secret-name" } ]

Deploy using Kubernetes YAML ZIP:

Download the External Issuer Kubernetes YAML ZIP file from the External Issuer download page. Unzip the ZIP file to a folder Open the manager/manager.yaml file in a text editor and perform the following edits: - Replace YOUR_INSTANCE with the name of your ServiceNow instance. - Set the CERTIFICATE_ENVIRONMENT to the desired environment (e.g., "development"), CERTIFICATE_PURPOSE to the purpose of the certificates (e.g: "internal", "external"), VALIDITY_PERIOD to the default validity period in days (e.g., "365"), CERTIFICATE_OWNER_GROUP and CERTIFICATE_OWNER to the respective SysIds if applicable. Update TASK_RETRY_INTERVAL_MINUTES f you want to change the polling period of external issuer to poll the state of task at different time interval. Lower value will mean external issuer will check the state of the task more frequently. - Update the image with the details of the Docker image built from the Docker recipe (eg: sn-external-issuer/sn_issuer:latest). You can also add imagePullSecrets if needed. Open a command prompt or terminal and navigate to the extracted folder and run the following commands: - kubectl create ns system - kubectl apply -f crd - kubectl apply -f rbac - kubectl apply -f issuers Create a secret for ServiceNow User using the below command kubectl create secret generic clusterissuer-servicenow-credentials --from-literal=user= --from-literal=password= -n Note: Secret should be in same namespace as your deployment Run the command below to deploy the External Issuer manager: kubectl apply -f manager/manager.yaml

Creating Certificate Request:

Certificate Request can be submitted to external issuers by creating a cert-manager Certificate object with issuerRef name as "clusterissuer-servicenow" and issuerRef group as "servicenow-issuer.servicenow.com"

Sample Certificate File is also available in ~/sn-external-issuer-kubernetes-yaml/samples/certificate_clusterissuer.yaml

Note : YAMLs are space sensitive please make sure the spacing is proper after pasting if you are copying the below sample

Sample Certificate Object:

apiVersion: cert-manager.io/v1 kind: Certificate metadata: name: certificate-by-clusterissuer spec: commonName: certificate-by-clusterissuer.servicenow.com secretName: certificate-by-clusterissuer dnsNames: - servicenow.com - foo.servicenow.com subject: organizationalUnits: - ITOM organizations: - ServiceNow, Inc. provinces: - California localities: - Santa Clara countries: - US issuerRef: name: clusterissuer-servicenow group: servicenow-issuer.servicenow.com kind: ClusterIssuer