Skip to content

Latest commit

 

History

History
202 lines (162 loc) · 8.99 KB

README.md

File metadata and controls

202 lines (162 loc) · 8.99 KB
Raw

KMS Issuer

Build Status CodeQL Status E2E Tests Helm Chart Tests

KMS issuer is a cert-manager Certificate Request controller that uses AWS KMS to sign the certificate request.

Getting started

In this guide, we assume that you have a Kubernetes environment with a cert-manager version supporting CertificateRequest issuers, cert-manager v0.11.0 or higher.

For any details on Cert-Manager, check the official documentation.

Install

You can install the controller using the official helm chart:

helm repo add kms-issuer 'https://skyscanner.github.io/kms-issuer'
helm repo update

To install the chart with the release name kms-issuer:

helm upgrade --install kms-issuer kms-issuer/kms-issuer --namespace kms-issuer-system --create-namespace

Usage

  1. Install cert-manager. The operator has been tested with version v0.15.1
kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.15.1/cert-manager.yaml
  1. Install and run the kms-issuer

Install the kms-issuer Kubernetes Custom Resources and start the controller.

# Install CRD
make install
# Run the controller (you must have have a role able to create/access KMS keys)
make run
  1. Create a KMS Key

You need a valid KMS asymetric key that as the ability to SIGN_VERIFY messages. Currently, Cloudformation does not support KMS SIGN_VERIFY keys. To simply the provisioning process, the kms-issuer operator provides a dedicated controller for provisioning a valid KMS key.

cat << EOF | kubectl apply -f -
---
apiVersion: cert-manager.skyscanner.net/v1alpha1
kind: KMSKey
metadata:
  name: kmskey-sample
spec:
  aliasName: alias/kms-issuer-example
  description: a kms-issuer example kms key
  customerMasterKeySpec: RSA_2048
  tags:
    project: kms-issuer
  deletionPolicy: Delete
  deletionPendingWindowInDays: 7
EOF
  1. Create a KMS issuer object
cat << EOF | kubectl apply -f -
---
apiVersion: cert-manager.skyscanner.net/v1alpha1
kind: KMSIssuer
metadata:
  name: kms-issuer
  namespace: default
spec:
  keyId: alias/kms-issuer-example # The KMS key id or alias
  commonName: My Root CA # The common name for the root certificate
  duration: 87600h # 10 years
EOF

At this point, the operator geneates a public root certificate signed using the provided KMS key. You can inspect it with the following command:

kubectl get kmsissuer kms-issuer -o json | jq -r ".status.certificate" |  base64 --decode  | openssl x509 -noout -text
  1. Finally, create a Certificate request that will be signed by our KMS issuer.
cat << EOF | kubectl apply -f -
---
apiVersion: cert-manager.io/v1
kind: Certificate
metadata:
  name: example-com
  namespace: default
spec:
  # Secret names are always required.
  secretName: example-com-tls
  duration: 8760h # 1 year
  renewBefore: 360h # 15d
  subject:
    organizations:
      - skyscanner
  # The use of the common name field has been deprecated since 2000 and is
  # discouraged from being used.
  commonName: example.com
  isCA: false
  privateKey:
    algorithm: RSA
    encoding: PKCS1
    size: 2048
  usages:
    - server auth
    - client auth
  # At least one of a DNS Name, URI, or IP address is required.
  dnsNames:
    - example.com
    - www.example.com
  uris:
    - spiffe://cluster.local/ns/sandbox/sa/example
  ipAddresses:
    - 192.168.0.5
  # Issuer references are always required.
  issuerRef:
    name: kms-issuer
    # We can reference ClusterIssuers by changing the kind here.
    # The default value is Issuer (i.e. a locally namespaced Issuer)
    kind: KMSIssuer
    # This is optional since cert-manager will default to this value however
    # if you are using an external issuer, change this to that issuer group.
    group: cert-manager.skyscanner.net
EOF

You now have a key pair signed by KMS

kubectl get secret example-com-tls

API Reference

KMSKey

A KMSKey resource is used to create an AWS KMS asymetric key compatible with the KMS issuer.

Field Type Description
apiVersion string cert-manager.skyscanner.net/v1alpha1
kind string KMSKey
metadata object Refer to the Kubernetes API documentation for metadata fields.
spec object Desired state of the KMSKey resource.
spec.aliasName string the alias name for the kms key. This value must begin with alias/ followed by a name, such as alias/ExampleAlias.
spec.description string Description for the key. (optional)
spec.customerMasterKeySpec string Determines the signing algorithms that the CMK supports. Only RSA_2048 is currently supported. (optional, default=RSA_2048)
spec.policy string The key policy to attach to the CMK. (optional)
spec.tags object A list of tags for the key. (optional)
spec.deletionPolicy string Policy to deletes the alias and key on object deletion. Either Retain or Delete. (optional, default=Retain).
spec.deletionPendingWindowInDays int Number of days before the KMS key gets deleted. If you include a value, it must be between 7 and 30, inclusive. If you do not include a value, it defaults to 30. (optional)

KMSIssuer

A KMSIssuer resource configures a new Cert-Manager external issuer.

Field Type Description
apiVersion string cert-manager.skyscanner.net/v1alpha1
kind string KMSIssuer
metadata object Refer to the Kubernetes API documentation for metadata fields.
spec object Desired state of the KMSIssuer resource.
spec.keyId string The unique identifier for the customer master key
spec.commonName string The common name to be used on the Certificate.
spec.duration duration Certificate default Duration. (optional, default=26280h aka 3 years)
spec.renewBefore duration The amount of time before the certificate’s notAfter time that the issuer will begin to attempt to renew the certificate. If this value is greater than the total duration of the certificate (i.e. notAfter - notBefore), it will be automatically renewed 2/3rds of the way through the certificate’s duration.

The NotBefore field on the certificate is set to the current time rounded down by the renewal interval. For example, if the certificate is renewed every hour, the NotBefore field is set to the beggining of the hour. If the certificate is renewed every day, the NotBefore field is set to the beggining of the day. This allows the generation of consistent certificates regardless of when it has been generated during the renewal period, or recreate the same certificate after a backup/restore of your kubernetes cluster. For more details on the computation, check the time.Truncate function.

Disable Approval Check

The KMS Issuer will wait for CertificateRequests to have an approved condition set before signing. If using an older version of cert-manager (pre v1.3), you can disable this check by supplying the command line flag -enable-approved-check=false to the Issuer Deployment.

Contributing

Kms-Issuer is built using the Kubebuilder framework. See the official documentation to get started and check CONTRIBUTING.md for more details.

Security

Check SECURITY.md.