{"id":19671698,"url":"https://github.com/skyscanner/kms-issuer","last_synced_at":"2025-04-29T01:30:37.824Z","repository":{"id":37092336,"uuid":"269356520","full_name":"Skyscanner/kms-issuer","owner":"Skyscanner","description":"KMS issuer is a cert-manager Certificate Request controller that uses AWS KMS to sign the certificate request.","archived":false,"fork":false,"pushed_at":"2024-03-17T05:21:21.000Z","size":1083,"stargazers_count":62,"open_issues_count":27,"forks_count":19,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-04-05T12:04:21.588Z","etag":null,"topics":["aws","cert-manager","certificates","hacktoberfest","kms","kubernetes","x509"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Skyscanner.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":null,"code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":"CODEOWNERS","security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-06-04T12:41:56.000Z","updated_at":"2024-10-21T21:37:24.000Z","dependencies_parsed_at":"2024-06-22T22:04:21.904Z","dependency_job_id":null,"html_url":"https://github.com/Skyscanner/kms-issuer","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skyscanner%2Fkms-issuer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skyscanner%2Fkms-issuer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skyscanner%2Fkms-issuer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Skyscanner%2Fkms-issuer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Skyscanner","download_url":"https://codeload.github.com/Skyscanner/kms-issuer/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251415574,"owners_count":21585855,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["aws","cert-manager","certificates","hacktoberfest","kms","kubernetes","x509"],"created_at":"2024-11-11T17:09:30.054Z","updated_at":"2025-04-29T01:30:37.174Z","avatar_url":"https://github.com/Skyscanner.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# KMS Issuer\n\n[![Build Status](https://github.com/Skyscanner/kms-issuer/actions/workflows/test-build.yml/badge.svg?branch=main)](https://github.com/Skyscanner/kms-issuer/actions)\n[![CodeQL Status](https://github.com/Skyscanner/kms-issuer/actions/workflows/code-quality.yml/badge.svg?branch=main)](https://github.com/Skyscanner/kms-issuer/actions)\n[![E2E Tests](https://github.com/Skyscanner/kms-issuer/actions/workflows/e2e.yaml/badge.svg?branch=main)](https://github.com/Skyscanner/kms-issuer/actions)\n[![Helm Chart Tests](https://github.com/Skyscanner/kms-issuer/actions/workflows/helm.yml/badge.svg?branch=main)](https://github.com/Skyscanner/kms-issuer/actions)\n\nKMS issuer is a [cert-manager](https://cert-manager.io/) Certificate Request controller that uses [AWS KMS](https://aws.amazon.com/kms/) to sign the certificate request.\n\n## Getting started\n\nIn this guide, we assume that you have a [Kubernetes](https://kubernetes.io/) environment with a cert-manager version supporting CertificateRequest issuers, cert-manager v0.11.0 or higher.\n\nFor any details on Cert-Manager, check the [official documentation](https://cert-manager.io/docs/usage/).\n\n## Install\n\nYou can install the controller using the official helm chart:\n\n```console\nhelm repo add kms-issuer 'https://skyscanner.github.io/kms-issuer'\nhelm repo update\n```\n\nTo install the chart with the release name `kms-issuer`:\n\n```console\nhelm upgrade --install kms-issuer kms-issuer/kms-issuer --namespace kms-issuer-system --create-namespace\n```\n\n### Usage\n\n1. Install [cert-manager](https://cert-manager.io/docs/installation/). The operator has been tested with version v0.15.1\n\n```bash\nkubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.15.1/cert-manager.yaml\n```\n\n2. Install and run the kms-issuer\n\nInstall the kms-issuer [Kubernetes Custom Resources](https://kubernetes.io/docs/concepts/extend-kubernetes/api-extension/custom-resources/) and start the controller.\n\n```bash\n# Install CRD\nmake install\n# Run the controller (you must have have a role able to create/access KMS keys)\nmake run\n```\n\n3. Create a KMS Key\n\nYou need a valid KMS asymetric key that as the ability to [SIGN_VERIFY](https://docs.aws.amazon.com/kms/latest/APIReference/API_Sign.html) messages.\nCurrently, Cloudformation [does not support](https://github.com/aws-cloudformation/aws-cloudformation-coverage-roadmap/issues/337) KMS SIGN_VERIFY keys.\nTo simply the provisioning process, the kms-issuer operator provides a dedicated controller for provisioning a valid KMS key.\n\n```yaml\ncat \u003c\u003c EOF | kubectl apply -f -\n---\napiVersion: cert-manager.skyscanner.net/v1alpha1\nkind: KMSKey\nmetadata:\n  name: kmskey-sample\nspec:\n  aliasName: alias/kms-issuer-example\n  description: a kms-issuer example kms key\n  customerMasterKeySpec: RSA_2048\n  tags:\n    project: kms-issuer\n  deletionPolicy: Delete\n  deletionPendingWindowInDays: 7\nEOF\n```\n\n4. Create a KMS issuer object\n\n```yaml\ncat \u003c\u003c EOF | kubectl apply -f -\n---\napiVersion: cert-manager.skyscanner.net/v1alpha1\nkind: KMSIssuer\nmetadata:\n  name: kms-issuer\n  namespace: default\nspec:\n  keyId: alias/kms-issuer-example # The KMS key id or alias\n  commonName: My Root CA # The common name for the root certificate\n  duration: 87600h # 10 years\nEOF\n```\n\nAt this point, the operator geneates a public root certificate signed using the provided KMS key. You can inspect it with the following command:\n\n```bash\nkubectl get kmsissuer kms-issuer -o json | jq -r \".status.certificate\" |  base64 --decode  | openssl x509 -noout -text\n```\n\n6. Finally, create a Certificate request that will be signed by our KMS issuer.\n\n```yaml\ncat \u003c\u003c EOF | kubectl apply -f -\n---\napiVersion: cert-manager.io/v1\nkind: Certificate\nmetadata:\n  name: example-com\n  namespace: default\nspec:\n  # Secret names are always required.\n  secretName: example-com-tls\n  duration: 8760h # 1 year\n  renewBefore: 360h # 15d\n  subject:\n    organizations:\n      - skyscanner\n  # The use of the common name field has been deprecated since 2000 and is\n  # discouraged from being used.\n  commonName: example.com\n  isCA: false\n  privateKey:\n    algorithm: RSA\n    encoding: PKCS1\n    size: 2048\n  usages:\n    - server auth\n    - client auth\n  # At least one of a DNS Name, URI, or IP address is required.\n  dnsNames:\n    - example.com\n    - www.example.com\n  uris:\n    - spiffe://cluster.local/ns/sandbox/sa/example\n  ipAddresses:\n    - 192.168.0.5\n  # Issuer references are always required.\n  issuerRef:\n    name: kms-issuer\n    # We can reference ClusterIssuers by changing the kind here.\n    # The default value is Issuer (i.e. a locally namespaced Issuer)\n    kind: KMSIssuer\n    # This is optional since cert-manager will default to this value however\n    # if you are using an external issuer, change this to that issuer group.\n    group: cert-manager.skyscanner.net\nEOF\n```\n\nYou now have a key pair signed by KMS\n\n```bash\nkubectl get secret example-com-tls\n```\n\n## API Reference\n\n### KMSKey\n\nA KMSKey resource is used to create an [AWS KMS](https://aws.amazon.com/kms/) asymetric key compatible with the KMS issuer.\n\n| Field                              | Type   | Description |\n| ---------------------------------- | ------ | ----------- |\n| `apiVersion`                       | string | `cert-manager.skyscanner.net/v1alpha1` |\n| `kind`                             | string | `KMSKey` |\n| `metadata`                         | object | Refer to the Kubernetes API [documentation][kubernetes-meta] for `metadata` fields. |\n| `spec`                             | object | Desired state of the KMSKey resource. |\n| `spec.aliasName`                   | string | the alias name for the kms key. This value must begin with alias/ followed by a name, such as alias/ExampleAlias. |\n| `spec.description`                 | string | Description for the key. (optional) |\n| `spec.customerMasterKeySpec`       | string | Determines the signing algorithms that the CMK supports. Only RSA_2048 is currently supported. (optional, default=RSA_2048) |\n| `spec.policy`                      | string | The key policy to attach to the CMK. (optional) |\n| `spec.tags`                        | object | A list of tags for the key. (optional) |\n| `spec.deletionPolicy`              | string | Policy to deletes the alias and key on object deletion. Either `Retain` or `Delete`. (optional, default=Retain). |\n| `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) |\n### KMSIssuer\n\nA KMSIssuer resource configures a new [Cert-Manager external issuer](https://cert-manager.io/docs/configuration/external).\n\n| Field              | Type     | Description |\n| ------------------ | -------- | ----------- |\n| `apiVersion`       | string   | `cert-manager.skyscanner.net/v1alpha1` |\n| `kind`             | string   | `KMSIssuer` |\n| `metadata`         | object   | Refer to the Kubernetes API [documentation][kubernetes-meta] for `metadata` fields.  |\n| `spec`             | object   | Desired state of the KMSIssuer resource. |\n| `spec.keyId`       | string   | The unique identifier for the customer master key |\n| `spec.commonName`  | string   | The common name to be used on the Certificate. |\n| `spec.duration`    | duration | Certificate default Duration. (optional, default=26280h aka 3 years) |\n| `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. \u003cbr\u003e \u003cbr\u003e 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](https://golang.org/pkg/time/#Time.Truncate) function. |\n\n[kubernetes-meta]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/#objectmeta-v1-meta\n\n## Disable Approval Check\n\nThe KMS Issuer will wait for CertificateRequests to have an [approved condition\nset](https://cert-manager.io/docs/concepts/certificaterequest/#approval) before\nsigning. If using an older version of cert-manager (pre v1.3), you can disable\nthis check by supplying the command line flag `-enable-approved-check=false` to\nthe Issuer Deployment.\n\n## Contributing\n\nKms-Issuer is built using the [Kubebuilder](https://book.kubebuilder.io/) framework. See the [official documentation](https://book.kubebuilder.io/quick-start.html) to get started and check [CONTRIBUTING.md](CONTRIBUTING.md) for more details.\n\n## Security\n\nCheck [SECURITY.md](SECURITY.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskyscanner%2Fkms-issuer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fskyscanner%2Fkms-issuer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fskyscanner%2Fkms-issuer/lists"}