{"id":16777314,"url":"https://github.com/githubixx/ansible-role-cert-manager-kubernetes","last_synced_at":"2025-06-26T15:32:32.849Z","repository":{"id":43816292,"uuid":"321480787","full_name":"githubixx/ansible-role-cert-manager-kubernetes","owner":"githubixx","description":"Ansible role to install Jetstack cert-manager in a Kubernetes cluster","archived":false,"fork":false,"pushed_at":"2025-01-03T10:28:42.000Z","size":51,"stargazers_count":11,"open_issues_count":0,"forks_count":2,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-16T19:18:10.235Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/githubixx.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2020-12-14T21:46:39.000Z","updated_at":"2025-01-03T10:28:23.000Z","dependencies_parsed_at":"2025-01-03T23:02:25.864Z","dependency_job_id":null,"html_url":"https://github.com/githubixx/ansible-role-cert-manager-kubernetes","commit_stats":null,"previous_names":[],"tags_count":24,"template":false,"template_full_name":null,"purl":"pkg:github/githubixx/ansible-role-cert-manager-kubernetes","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubixx%2Fansible-role-cert-manager-kubernetes","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubixx%2Fansible-role-cert-manager-kubernetes/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubixx%2Fansible-role-cert-manager-kubernetes/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubixx%2Fansible-role-cert-manager-kubernetes/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/githubixx","download_url":"https://codeload.github.com/githubixx/ansible-role-cert-manager-kubernetes/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/githubixx%2Fansible-role-cert-manager-kubernetes/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":262094439,"owners_count":23257965,"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":[],"created_at":"2024-10-13T07:24:21.424Z","updated_at":"2025-06-26T15:32:32.821Z","avatar_url":"https://github.com/githubixx.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# cert-manager-kubernetes\n\nThis Ansible role installs [cert-manager](https://cert-manager.io/) on a Kubernetes cluster. Behind the doors it uses the official [Helm chart](https://charts.jetstack.io). Currently procedures like installing, upgrading and deleting the cert-manager deployment are supported.\n\n## Versions\n\nI tag every release and try to stay with [semantic versioning](http://semver.org). If you want to use the role I recommend to checkout the latest tag. The master branch is basically development while the tags mark stable releases. But in general I try to keep master in good shape too. A tag `12.0.0+1.16.2` means this is release `12.0.0` of this role and it contains cert-manager chart version `1.16.2`. If the role itself changes `X.Y.Z` before `+` will increase. If the cert-manager chart version changes `X.Y.Z` after `+` will increase too. This allows to tag bugfixes and new major versions of the role while it's still developed for a specific cert-manager release.\n\n## Requirements\n\nYou need to have [Helm 3](https://helm.sh/) binary installed on that host where `ansible-playbook` is executed. You can either\n\n- use your favorite package manager if your distribution includes `helm` in its repository (for Archlinux use `sudo pacman -S helm` e.g.)\n- or use one of the Ansible `Helm` roles (e.g. [helm](https://galaxy.ansible.com/gantsign/helm) - which gets also installed if you use `ansible-galaxy role install -vr requirements.yml`\n- or directly download the binary from [Helm releases)[https://github.com/helm/helm/releases]) and put it into `/usr/local/bin/` directory e.g.\n\nA properly configured `KUBECONFIG` is also needed (which is located at `${HOME}/.kube/config` by default). Normally if `kubectl` works with your cluster then everything should be already fine in this regards.\n\nAdditionally the Ansible `kubernetes.core` collection needs to be installed. This can be done by using the `collections.yml` file included in this role: `ansible-galaxy install -r collections.yml`.\n\nAnd of course you need a Kubernetes Cluster ;-)\n\n## Changelog\n\nsee [CHANGELOG](https://github.com/githubixx/ansible-role-cert-manager-kubernetes/blob/master/CHANGELOG.md)\n\n## Role Variables\n\n```yaml\n# Helm chart version\ncert_manager_chart_version: \"v1.16.2\"\n\n# Helm release name\ncert_manager_release_name: \"cert-manager\"\n\n# Helm repository name\ncert_manager_repo_name: \"jetstack\"\n\n# Helm chart name\ncert_manager_chart_name: \"{{ cert_manager_repo_name }}/{{ cert_manager_release_name }}\"\n\n# Helm chart URL\ncert_manager_chart_url: \"https://charts.jetstack.io\"\n\n# Kubernetes namespace where cert-manager resources should be installed\ncert_manager_namespace: \"cert-manager\"\n\n# The following list contains the configurable parameters of the cert-manager\n# Helm chart. For all possible values see:\n# https://artifacthub.io/packages/helm/cert-manager/cert-manager#configuration\n# But for most users \"installCRDs=true\" should be sufficient.\n# If true, CRD resources will be installed as part of the Helm chart.\n# If enabled, when uninstalling CRD resources will be deleted causing all\n# installed custom resources to be DELETED.\ncert_manager_values:\n  - crds.enabled=true\n  - crds.keep=true\n  - global.leaderElection.namespace=\"{{ cert_manager_namespace }}\"\n\n# If your Kubernetes control plane (`kube-apiserver` e.g.) has no route to the\n# Pods and Services you can configure the \"cert-manager-webhook\" container to\n# also listen on the host network which the controller and worker nodes share.\n# So in the example above the cert-manager webhook service will listen on\n# port \"30001\" in the pod network space and the host network. And the\n# \"webhook.url.host\" option specifies that the control plane should connect\n# to the webhook by connecting to \"worker:30001\" (of course you need to replace\n# \"worker\" with a real hostname e.g.). And to make sure that the webhook\n# TLS certificate has the correct DNS names `--dynamic-serving-dns-names`\n# option is specified too. It can be a list of DNS names actually. So you can\n# also add fully qualified domain names (FQDN) if you want of course.\n# (see also: https://github.com/jetstack/cert-manager/issues/2602)\n#  - webhook.securePort=\"30001\"\n#  - webhook.hostNetwork=true\n#  - webhook.url.host=\"worker:30001\"\n#  - webhook.extraArgs=\"{--dynamic-serving-dns-names=worker}\"\n\n# To install \"ClusterIssuer\" for Let's Encrypt (LE) \"cert_manager_le_clusterissuer_options\"\n# needs to be defined. The variable contains a list of hashes and can be defined\n# in \"group_vars/all.yml\" e.g.\n#\n# name:   Defines the name of the \"ClusterIssuer\"\n# email:  Use a valid e-mail address to be alerted by LE in case a certificate\n#         expires\n# server: Hostname part of the LE URL\n# private_key_secret_ref_name:  Name of the secret which stores the private key\n# solvers_http01_ingress_class: Value of \"kubernetes.io/ingress.class\" annotation.\n#                               Depends on your ingress controller. Common values\n#                               are \"traefik\" for Traefik or \"nginx\" for nginx.\n#\n# Besides \"email\" the following values can be used as is and will create valid\n# \"ClusterIssuer\" for Let's Encrypt staging and production. Only \"email\" needs\n# to be adjusted if Traefik is used as ingress controller. For other ingress\n# controllers \"solvers_http01_ingress_class\" needs to be adjusted too. Currently\n# only \"ClusterIssuer\" and \"http01\" solver is implemented. For definition also\n# see \"tasks/install-issuer.yml\".\n#\n# cert_manager_le_clusterissuer_options:\n#   - name: letsencrypt-prod\n#     email: insert@your-e-mail-address.here\n#     server: acme-v02\n#     private_key_secret_ref_name: letsencrypt-account-key\n#     solvers_http01_ingress_class: \"traefik\"\n#   - name: letsencrypt-staging\n#     email: insert@your-e-mail-address.here\n#     server: acme-staging-v02\n#     private_key_secret_ref_name: letsencrypt-staging-account-key\n#     solvers_http01_ingress_class: \"traefik\"\n```\n\n## Usage\n\nFirst check if you want to change any of the default values in `default/main.yml`. As usual those values can be overridden in `host_vars` or `group_vars`. Normally there is no need to change that much. Besides the `cert_manager_chart_version` you might want do add a few options to `cert_manager_values`. It contains the configurable parameters of the cert-manager Helm chart. The list is submitted \"as is\" to `helm` binary for `template`, `install` or `upgrade` commands.\n\nThe default action is to just render the Kubernetes resources YAML file after replacing all Jinja2 variables and stuff like that (that means not specifying any value via `--extra-vars action=...` to `ansible-playbook`). In the `Example Playbook` section below there is an `Example 2 (assign tag to role)`. The role `githubixx.cert_manager_kubernetes` has a tag `role-cert-manager-kubernetes` assigned.\n\nSo to render the YAML files the WOULD be applied (nothing will be installed at this time) and the playbook is called `k8s.yml` execute the following command:\n\n```bash\nansible-playbook --tags=role-cert-manager-kubernetes k8s.yml\n```\n\nOne of the final tasks is called `TASK [githubixx.cert-manager-kubernetes : Output rendered template]`. This allows to check the YAML file before cert-manager gets deployed. Probably the output isn't that \"pretty\" in your case. To get around this you can either set `ANSIBLE_STDOUT_CALLBACK=debug` environment variable or `stdout_callback = debug` in `ansible.cfg`. If you run the `ansible-playbook` command again now, the YAML output should now look way better.\n\nIf the rendered output contains everything you need, the role can be installed which finally deploys cert-manager (still assuming the playbook file is called `k8s.yml` - if not please adjust accordingly):\n\n```bash\nansible-playbook --tags=role-cert-manager-kubernetes --extra-vars action=install k8s.yml\n```\n\nTo check if everything was deployed use the usual `kubectl` commands like `kubectl -n \u003ccert_manager_namespace\u003e get pods -o wide`. Before the playbook finishes it waits for the first `cert-manager-webhooks` pod to become ready.\n\nSooner or later there will be a new cert-manager version and you want to upgrade. Before doing the upgrade read the cert-manager [upgrade guide](https://cert-manager.io/docs/installation/upgrading/) carefully! If everything is in place you basically only need to change `cert_manager_chart_version` variable e.g. from `v1.1.0` to `v1.2.0` to upgrade from `v1.1.0` to `v1.2.0`. So to do the update run\n\n```bash\nansible-playbook --tags=role-cert-manager-kubernetes --extra-vars action=upgrade k8s.yml\n```\n\nAnd finally if you want to get rid of cert-manager you can delete all resources (this of course deletes EVERYTHING cert-manager related and this might also include certificates and secrets cert-manager already created - so be careful!):\n\n```bash\nansible-playbook --tags=role-cert-manager-kubernetes --extra-vars action=delete k8s.yml\n```\n\n## Issuer\n\nThe role currently supports deploying a [ClusterIssuer](https://cert-manager.io/docs/concepts/issuer/) for [Let's Encrypt](https://letsencrypt.org/) (LE) for LE staging and production. The most relevant variable in this case is `cert_manager_le_clusterissuer_options`. Please see the role variables above for more information.\n\nAfter `cert_manager_le_clusterissuer_options` variable is adjusted accordingly the `ClusterIssuer` can be installed:\n\n```bash\nansible-playbook --tags=role-cert-manager-kubernetes --extra-vars action=install-issuer k8s.yml\n```\n\nAfter deploying the issuer the first time it takes a little bit until they are ready. To figure out if they are ready `kubectl` can be used:\n\n```bash\nkubectl get clusterissuers.cert-manager.io\n\nNAME                  READY   AGE\nletsencrypt-prod      True    10m\nletsencrypt-staging   True    11m\n```\n\nAfterwards a certificate can be issued. This happens outside of this Ansible role. E.g. to get a certificate for domain `www.domain.name` from Let's Encrypt staging server (this one is only for testing and doesn't issue a valid certificate that browsers will accept) create a YAML file (e.g. domain-name.yaml) like this:\n\n```yaml\n---\napiVersion: cert-manager.io/v1\nkind: Certificate\nmetadata:\n  name: cert-name\n  namespace: namespace-name\nspec:\n  commonName: www.domain.name\n  secretName: secret-name\n  dnsNames:\n    - www.domain.name\n  issuerRef:\n    name: letsencrypt-staging\n    kind: ClusterIssuer\n```\n\nAfter changing the values to your needs, apply this file with `kubectl --namespace \u003c...\u003e apply -f domain-name.yaml`.\n\nIf you request a `(Cluster)Issuer` or a `Certificate` you can watch `cert-manager` logs to see what's going on e.g. (of course replace `cert-manager-76d899dd6c-8q8b` with the name of your `cert-manager` pod and in case you use a different namespace for `cert-manager` also change the namespace accordingly):\n\n```bash\nkubectl -n cert-manager logs -f --tail=50 cert-manager-76d899dd6c-8q8b\n```\n\nTo get information about a `Certificate` this command can be used:\n\n```bash\nkubectl -n your-namespace get certificate cert-name -o yaml\n```\n\nAnd in case you want to delete the `ClusterIssuer` use:\n\n```bash\nansible-playbook --tags=role-cert-manager-kubernetes --extra-vars action=delete-issuer k8s.yml\n```\n\n## Example Playbook\n\nExample 1 (without role tag):\n\n```yaml\n---\n- hosts: cert_manager\n  roles:\n    - githubixx.cert_manager_kubernetes\n```\n\nExample 2 (assign tag to role):\n\n```yaml\n---\n-\n  hosts: cert_manager\n  roles:\n    - role: githubixx.cert_manager_kubernetes\n      tags: role-cert-manager-kubernetes\n```\n\n## License\n\nGNU GENERAL PUBLIC LICENSE Version 3\n\n## Author Information\n\n[http://www.tauceti.blog](http://www.tauceti.blog)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithubixx%2Fansible-role-cert-manager-kubernetes","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgithubixx%2Fansible-role-cert-manager-kubernetes","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgithubixx%2Fansible-role-cert-manager-kubernetes/lists"}