|
| 1 | +<a href="https://kubernetes.io"> |
| 2 | + <img src="https://raw.githubusercontent.com/cert-manager/cert-manager/d53c0b9270f8cd90d908460d69502694e1838f5f/logo/logo-small.png" alt="Terraform logo" title="K8s" align="left" height="50" /> |
| 3 | +</a> |
| 4 | + |
| 5 | +# Command Cert Manager Issuer Usage |
| 6 | + |
| 7 | +[](https://goreportcard.com/report/github.com/Keyfactor/command-cert-manager-issuer) |
| 8 | +[](https://img.shields.io/badge/License-Apache%202.0-blue.svg) |
| 9 | + |
| 10 | +The cert-manager external issuer for Keyfactor Command can be used to issue certificates from Keyfactor Command using cert-manager. |
| 11 | + |
| 12 | +### Documentation Tree |
| 13 | +* [Installation](install.markdown) |
| 14 | +* [Example Usage](example.markdown) |
| 15 | +* [Customization](annotations.markdown) |
| 16 | +* [Testing the Source](testing.markdown) |
| 17 | + |
| 18 | +### Keyfactor Command Configuration |
| 19 | +The Command Issuer for cert-manager populates metadata fields on issued certificates in Command pertaining to the K8s cluster and cert-manager Issuer/ClusterIssuer. Before deploying Issuers/ClusterIssuers, these metadata fields must be created in Command. To easily create these metadata fields, use the `kfutil` Keyfactor command line tool that offers convenient and powerful command line access to the Keyfactor platform. Before proceeding, ensure that `kfutil` is installed and configured by following the instructions here: [https://github.com/Keyfactor/kfutil](https://github.com/Keyfactor/kfutil). |
| 20 | + |
| 21 | +Then, use the `import` command to import the metadata fields into Command: |
| 22 | +```shell |
| 23 | +cat <<EOF >> metadata.json |
| 24 | +{ |
| 25 | + "Collections": [], |
| 26 | + "MetadataFields": [ |
| 27 | + { |
| 28 | + "AllowAPI": true, |
| 29 | + "DataType": 1, |
| 30 | + "Description": "The namespace that the issuer resource was created in.", |
| 31 | + "Name": "Issuer-Namespace" |
| 32 | + }, |
| 33 | + { |
| 34 | + "AllowAPI": true, |
| 35 | + "DataType": 1, |
| 36 | + "Description": "The certificate reconcile ID that the controller used to issue this certificate.", |
| 37 | + "Name": "Controller-Reconcile-Id" |
| 38 | + }, |
| 39 | + { |
| 40 | + "AllowAPI": true, |
| 41 | + "DataType": 1, |
| 42 | + "Description": "The namespace that the CertificateSigningRequest resource was created in.", |
| 43 | + "Name": "Certificate-Signing-Request-Namespace" |
| 44 | + }, |
| 45 | + { |
| 46 | + "AllowAPI": true, |
| 47 | + "DataType": 1, |
| 48 | + "Description": "The namespace that the controller container is running in.", |
| 49 | + "Name": "Controller-Namespace" |
| 50 | + }, |
| 51 | + { |
| 52 | + "AllowAPI": true, |
| 53 | + "DataType": 1, |
| 54 | + "Description": "The type of issuer that the controller used to issue this certificate.", |
| 55 | + "Name": "Controller-Kind" |
| 56 | + }, |
| 57 | + { |
| 58 | + "AllowAPI": true, |
| 59 | + "DataType": 1, |
| 60 | + "Description": "The group name of the resource that the Issuer or ClusterIssuer controller is managing.", |
| 61 | + "Name": "Controller-Resource-Group-Name" |
| 62 | + }, |
| 63 | + { |
| 64 | + "AllowAPI": true, |
| 65 | + "DataType": 1, |
| 66 | + "Description": "The name of the K8s issuer resource", |
| 67 | + "Name": "Issuer-Name" |
| 68 | + } |
| 69 | + ], |
| 70 | + "ExpirationAlerts": [], |
| 71 | + "IssuedCertAlerts": [], |
| 72 | + "DeniedCertAlerts": [], |
| 73 | + "PendingCertAlerts": [], |
| 74 | + "Networks": [], |
| 75 | + "WorkflowDefinitions": [], |
| 76 | + "BuiltInReports": [], |
| 77 | + "CustomReports": [], |
| 78 | + "SecurityRoles": [] |
| 79 | +} |
| 80 | +EOF |
| 81 | +kfutil import --metadata --file metadata.json |
| 82 | +``` |
| 83 | + |
| 84 | +### Authentication |
| 85 | +Authentication to the Command platform is done using basic authentication. The credentials must be provided as a Kubernetes `kubernetes.io/basic-auth` secret. These credentials should be for a user with "Certificate Enrollment: Enroll CSR" and "API: Read" permissions in Command. |
| 86 | + |
| 87 | +Create a `kubernetes.io/basic-auth` secret with the Keyfactor Command username and password: |
| 88 | +```shell |
| 89 | +cat <<EOF | kubectl -n command-issuer-system apply -f - |
| 90 | +apiVersion: v1 |
| 91 | +kind: Secret |
| 92 | +metadata: |
| 93 | + name: command-secret |
| 94 | +type: kubernetes.io/basic-auth |
| 95 | +data: |
| 96 | + username: <base64 encoded (domain\\)username> |
| 97 | + password: <base64 encoded password> |
| 98 | +EOF |
| 99 | +``` |
| 100 | + |
| 101 | +If the Command server is configured to use a self-signed certificate or with a certificate signed by an untrusted root, the CA certificate must be provided as a Kubernetes secret. |
| 102 | +```shell |
| 103 | +kubectl -n command-issuer-system create secret generic command-ca-secret --from-file=ca.crt |
| 104 | +``` |
| 105 | + |
| 106 | +### Creating Issuer and ClusterIssuer resources |
| 107 | +The `command-issuer.keyfactor.com/v1alpha1` API version supports Issuer and ClusterIssuer resources. |
| 108 | +The Command controller will automatically detect and process resources of both types. |
| 109 | + |
| 110 | +The Issuer resource is namespaced, while the ClusterIssuer resource is cluster-scoped. |
| 111 | +For example, ClusterIssuer resources can be used to issue certificates for resources in multiple namespaces, whereas Issuer resources can only be used to issue certificates for resources in the same namespace. |
| 112 | + |
| 113 | +The `spec` field of both the Issuer and ClusterIssuer resources use the following fields: |
| 114 | +* `hostname` - The hostname of the Keyfactor Command server - The signer sets the protocol to `https` and automatically trims the trailing path from this field, if it exists. Additionally, the base Command API path is automatically set to `/KeyfactorAPI` and cannot be changed. |
| 115 | +* `commandSecretName` - The name of the Kubernetes `kubernetes.io/basic-auth` secret containing credentials to the Keyfactor instance |
| 116 | +* `certificateTemplate` - The short name corresponding to a template in Command that will be used to issue certificates. |
| 117 | +* `certificateAuthorityLogicalName` - The logical name of the CA to use to sign the certificate request |
| 118 | +* `certificateAuthorityHostname` - The CAs hostname to use to sign the certificate request |
| 119 | +* `caSecretName` - The name of the Kubernetes secret containing the CA certificate. This field is optional and only required if the Command server is configured to use a self-signed certificate or with a certificate signed by an untrusted root. |
| 120 | + |
| 121 | +###### If a different combination of hostname/certificate authority/certificate profile/end entity profile is required, a new Issuer or ClusterIssuer resource must be created. Each resource instantiation represents a single configuration. |
| 122 | + |
| 123 | +The following is an example of an Issuer resource: |
| 124 | +```shell |
| 125 | +cat <<EOF >> command-issuer.yaml |
| 126 | +apiVersion: command-issuer.keyfactor.com/v1alpha1 |
| 127 | +kind: Issuer |
| 128 | +metadata: |
| 129 | + labels: |
| 130 | + app.kubernetes.io/name: issuer |
| 131 | + app.kubernetes.io/instance: issuer-sample |
| 132 | + app.kubernetes.io/part-of: command-issuer |
| 133 | + app.kubernetes.io/created-by: command-issuer |
| 134 | +name: issuer-sample |
| 135 | +spec: |
| 136 | + hostname: "" |
| 137 | + commandSecretName: "" |
| 138 | + certificateTemplate: "" |
| 139 | + certificateAuthorityLogicalName: "" |
| 140 | + certificateAuthorityHostname: "" |
| 141 | + caSecretName: "" |
| 142 | +EOF |
| 143 | +kubectl -n command-issuer-system apply -f command-issuer.yaml |
| 144 | +``` |
| 145 | + |
| 146 | +###### :pushpin: Issuers can only issue certificates in the same namespace as the issuer resource. To issue certificates in multiple namespaces, use a ClusterIssuer. |
| 147 | + |
| 148 | +The following is an example of a ClusterIssuer resource: |
| 149 | +```shell |
| 150 | +cat <<EOF >> command-clusterissuer.yaml |
| 151 | +apiVersion: command-issuer.keyfactor.com/v1alpha1 |
| 152 | +kind: ClusterIssuer |
| 153 | +metadata: |
| 154 | + labels: |
| 155 | + app.kubernetes.io/name: clusterissuer |
| 156 | + app.kubernetes.io/instance: clusterissuer-sample |
| 157 | + app.kubernetes.io/part-of: command-issuer |
| 158 | + app.kubernetes.io/created-by: command-issuer |
| 159 | + name: clusterissuer-sample |
| 160 | +spec: |
| 161 | + hostname: "" |
| 162 | + commandSecretName: "" |
| 163 | + certificateTemplate: "" |
| 164 | + certificateAuthorityLogicalName: "" |
| 165 | + certificateAuthorityHostname: "" |
| 166 | + caSecretName: "" |
| 167 | +EOF |
| 168 | +kubectl -n command-issuer-system apply -f command-clusterissuer.yaml |
| 169 | +``` |
| 170 | + |
| 171 | +###### :pushpin: ClusterIssuers can issue certificates in any namespace. To issue certificates in a single namespace, use an Issuer. |
| 172 | + |
| 173 | +To create new resources from the above examples, replace the empty strings with the appropriate values and apply the resources to the cluster: |
| 174 | +```shell |
| 175 | +kubectl -n command-issuer-system apply -f issuer.yaml |
| 176 | +kubectl -n command-issuer-system apply -f clusterissuer.yaml |
| 177 | +``` |
| 178 | + |
| 179 | +### Using Issuer and ClusterIssuer resources |
| 180 | +Once the Issuer and ClusterIssuer resources are created, they can be used to issue certificates using cert-manager. |
| 181 | +The two most important concepts are `Certificate` and `CertificateRequest` resources. `Certificate` |
| 182 | +resources represent a single X.509 certificate and its associated attributes, and automatically renews the certificate |
| 183 | +and keeps it up to date. When `Certificate` resources are created, they create `CertificateRequest` resources, which |
| 184 | +use an Issuer or ClusterIssuer to actually issue the certificate. |
| 185 | + |
| 186 | +###### To learn more about cert-manager, see the [cert-manager documentation](https://cert-manager.io/docs/). |
| 187 | + |
| 188 | +The following is an example of a Certificate resource. This resource will create a corresponding CertificateRequest resource, |
| 189 | +and will use the `issuer-sample` Issuer resource to issue the certificate. Once issued, the certificate will be stored in a |
| 190 | +Kubernetes secret named `command-certificate`. |
| 191 | +```yaml |
| 192 | +apiVersion: cert-manager.io/v1 |
| 193 | +kind: Certificate |
| 194 | +metadata: |
| 195 | + name: command-certificate |
| 196 | +spec: |
| 197 | + commonName: command-issuer-sample |
| 198 | + secretName: command-certificate |
| 199 | + issuerRef: |
| 200 | + name: issuer-sample |
| 201 | + group: command-issuer.keyfactor.com |
| 202 | + kind: Issuer |
| 203 | +``` |
| 204 | +
|
| 205 | +###### :pushpin: Certificate resources support many more fields than the above example. See the [Certificate resource documentation](https://cert-manager.io/docs/usage/certificate/) for more information. |
| 206 | +
|
| 207 | +###### :pushpin: Since this certificate request called `command-certificate` is configured to use `issuer-sample`, it must be deployed in the same namespace as `issuer-sample`. |
| 208 | + |
| 209 | +Similarly, a CertificateRequest resource can be created directly. The following is an example of a CertificateRequest resource. |
| 210 | +```yaml |
| 211 | +apiVersion: cert-manager.io/v1 |
| 212 | +kind: CertificateRequest |
| 213 | +metadata: |
| 214 | + name: command-certificate |
| 215 | +spec: |
| 216 | + request: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURSBSRVFVRVNULS0tLS0KTUlJQ2REQ0NBVndDQVFBd0x6RUxNQWtHQTFVRUN4TUNTVlF4SURBZUJnTlZCQU1NRjJWcVltTmhYM1JsY25KaApabTl5YlY5MFpYTjBZV05qTUlJQklqQU5CZ2txaGtpRzl3MEJBUUVGQUFPQ0FROEFNSUlCQ2dLQ0FRRUF4blNSCklqZDZSN2NYdUNWRHZscXlFcUhKalhIazljN21pNTdFY3A1RXVnblBXa0YwTHBVc25PMld6WTE1bjV2MHBTdXMKMnpYSURhS3NtZU9ZQzlNOWtyRjFvOGZBelEreHJJWk5SWmg0cUZXRmpyNFV3a0EySTdUb05veitET2lWZzJkUgo1cnNmaFdHMmwrOVNPT3VscUJFcWVEcVROaWxyNS85OVpaemlBTnlnL2RiQXJibWRQQ1o5OGhQLzU0NDZhci9NCjdSd2ludjVCMnNRcWM0VFZwTTh3Nm5uUHJaQXA3RG16SktZbzVOQ3JyTmw4elhIRGEzc3hIQncrTU9DQUw0T00KTkJuZHpHSm5KenVyS0c3RU5UT3FjRlZ6Z3liamZLMktyMXRLS3pyVW5keTF1bTlmTWtWMEZCQnZ0SGt1ZG0xdwpMUzRleW1CemVtakZXQi9yRVFJREFRQUJvQUF3RFFZSktvWklodmNOQVFFTEJRQURnZ0VCQUJhdFpIVTdOczg2Cmgxc1h0d0tsSi95MG1peG1vRWJhUTNRYXAzQXVFQ2x1U09mdjFDZXBQZjF1N2dydEp5ZGRha1NLeUlNMVNzazAKcWNER2NncUsxVVZDR21vRkp2REZEaEUxMkVnM0ZBQ056UytFNFBoSko1N0JBSkxWNGZaeEpZQ3JyRDUxWnk3NgpPd01ORGRYTEVib0w0T3oxV3k5ZHQ3bngyd3IwWTNZVjAyL2c0dlBwaDVzTHl0NVZOWVd6eXJTMzJYckJwUWhPCnhGMmNNUkVEMUlaRHhuMjR2ZEtINjMzSFo1QXd0YzRYamdYQ3N5VW5mVUE0ZjR1cHBEZWJWYmxlRFlyTW1iUlcKWW1NTzdLTjlPb0MyZ1lVVVpZUVltdHlKZTJkYXlZSHVyUUlpK0ZsUU5zZjhna1hYeG45V2drTnV4ZTY3U0x5dApVNHF4amE4OCs1ST0KLS0tLS1FTkQgQ0VSVElGSUNBVEUgUkVRVUVTVC0tLS0t |
| 217 | + issuerRef: |
| 218 | + name: issuer-sample |
| 219 | + group: command-issuer.keyfactor.com |
| 220 | + kind: Issuer |
| 221 | +``` |
| 222 | + |
| 223 | +### Approving Certificate Requests |
| 224 | +Unless the cert-manager internal approver automatically approves the request, newly created CertificateRequest resources |
| 225 | +will be in a `Pending` state until they are approved. CertificateRequest resources can be approved manually by using |
| 226 | +[cmctl](https://cert-manager.io/docs/reference/cmctl/#approve-and-deny-certificaterequests). The following is an example |
| 227 | +of approving a CertificateRequest resource named `command-certificate` in the `command-issuer-system` namespace. |
| 228 | +```shell |
| 229 | +cmctl -n command-issuer-system approve ejbca-certificate |
| 230 | +``` |
| 231 | + |
| 232 | +Once a certificate request has been approved, the certificate will be issued and stored in the secret specified in the |
| 233 | +CertificateRequest resource. The following is an example of retrieving the certificate from the secret. |
| 234 | +```shell |
| 235 | +kubectl get secret command-certificate -n command-issuer-system -o jsonpath='{.data.tls\.crt}' | base64 -d |
| 236 | +``` |
| 237 | + |
| 238 | +###### To learn more about certificate approval and RBAC configuration, see the [cert-manager documentation](https://cert-manager.io/docs/concepts/certificaterequest/#approval). |
| 239 | + |
| 240 | +###### :pushpin: If the certificate was issued successfully, the Approved and Ready field will both be set to `True`. |
| 241 | + |
| 242 | +Next, see the [example usage](example.markdown) documentation for a complete example of using the Command Issuer for cert-manager. |
0 commit comments