{"id":22220847,"url":"https://github.com/nokia/ncm-issuer","last_synced_at":"2025-09-12T18:21:13.270Z","repository":{"id":37008962,"uuid":"472657380","full_name":"nokia/ncm-issuer","owner":"nokia","description":"cert-manager external issuer for integration with the Nokia NetGuard Certificate Manager (NCM) PKI system","archived":false,"fork":false,"pushed_at":"2025-06-18T17:28:20.000Z","size":3010,"stargazers_count":15,"open_issues_count":0,"forks_count":8,"subscribers_count":8,"default_branch":"main","last_synced_at":"2025-06-18T17:40:03.116Z","etag":null,"topics":["cert-manager","certificate","certifier","golang","helm","kubernetes","netguard","netguard-certificate-manager","pki"],"latest_commit_sha":null,"homepage":"https://nokia.github.io/ncm-issuer/docs/","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/nokia.png","metadata":{"files":{"readme":"README.md","changelog":null,"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,"zenodo":null}},"created_at":"2022-03-22T07:28:40.000Z","updated_at":"2025-06-18T17:28:24.000Z","dependencies_parsed_at":"2024-07-23T17:28:49.021Z","dependency_job_id":"ad3db50d-5cf7-46d5-ba9e-84b9af3a7270","html_url":"https://github.com/nokia/ncm-issuer","commit_stats":null,"previous_names":[],"tags_count":10,"template":false,"template_full_name":null,"purl":"pkg:github/nokia/ncm-issuer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fncm-issuer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fncm-issuer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fncm-issuer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fncm-issuer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/nokia","download_url":"https://codeload.github.com/nokia/ncm-issuer/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/nokia%2Fncm-issuer/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261084368,"owners_count":23107310,"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":["cert-manager","certificate","certifier","golang","helm","kubernetes","netguard","netguard-certificate-manager","pki"],"created_at":"2024-12-02T23:10:31.834Z","updated_at":"2025-09-12T18:21:13.251Z","avatar_url":"https://github.com/nokia.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003c!-- markdownlint-disable  MD013 MD014 MD033 --\u003e\n# ncm-issuer\n\n\u003cdiv id=\"top\"\u003e\u003c/div\u003e\n\n[![build](https://github.com/nokia/ncm-issuer/actions/workflows/build.yml/badge.svg?branch=main)](https://github.com/nokia/ncm-issuer/actions/workflows/build.yml)\n[![e2e](https://github.com/nokia/ncm-issuer/actions/workflows/e2e.yml/badge.svg?branch=main)](https://github.com/nokia/ncm-issuer/actions/workflows/e2e.yml)\n[![Go Report Card](https://goreportcard.com/badge/github.com/nokia/ncm-issuer)](https://goreportcard.com/report/github.com/nokia/ncm-issuer)\n\n[![Coverage](https://sonarcloud.io/api/project_badges/measure?project=nokia_ncm-issuer\u0026metric=coverage)](https://sonarcloud.io/summary/new_code?id=nokia_ncm-issuer)\n[![Maintainability Rating](https://sonarcloud.io/api/project_badges/measure?project=nokia_ncm-issuer\u0026metric=sqale_rating)](https://sonarcloud.io/summary/new_code?id=nokia_ncm-issuer)\n[![Security Rating](https://sonarcloud.io/api/project_badges/measure?project=nokia_ncm-issuer\u0026metric=security_rating)](https://sonarcloud.io/summary/new_code?id=nokia_ncm-issuer)\n[![Reliability Rating](https://sonarcloud.io/api/project_badges/measure?project=nokia_ncm-issuer\u0026metric=reliability_rating)](https://sonarcloud.io/summary/new_code?id=nokia_ncm-issuer)\n\n\u003cp align=\"center\"\u003e\n   \u003cimg src=\"./assets/ncm-issuer-logo.png\" alt=\"ncm-issuer-logo\" width=\"35%\"/\u003e\n\u003c/p\u003e\n\nncm-issuer is a [Kubernetes](https://kubernetes.io) controller (external [cert-manager](https://cert-manager.io/) issuer) that allows to integrate with\n[Nokia NetGuard Certificate Manager (NCM)](https://www.nokia.com/networks/products/pki-authority-with-netguard-certificate-manager/)\nPKI system to sign certificate requests. \n\nThe integration with NCM makes it easy to obtain non-self-signed certificates for applications and to ensure that they are valid and up-to-date.\n\n## Table of contents\n\n* [Prerequisites](#prerequisites)\n* [Installation and configuration](#installation-and-configuration)\n  * [Installing using Helm](#installing-using-helm)\n    * [Using own (local or remote) registry](#using-own--local-or-remote--registry)\n    * [Configuration](#configuration)\n      * [NCM REST API credentials](#ncm-api-credentials)\n      * [TLS without client authentication](#tls-without-client-authentication)\n      * [TLS with client authentication](#tls-with-client-authentication)\n* [Custom resource definitions (CRDs)](#custom-resource-definitions--crds-)\n  * [Issuer resource](#issuer-resource)\n  * [ClusterIssuer resource](#clusterissuer-resource)\n  * [Issuer and ClusterIssuer fields overview](#issuer-and-clusterissuer-fields-overview)\n* [Usage](#usage)\n  * [Create an Issuer](#create-an-issuer)\n  * [Signing certificate](#signing-certificate)\n  * [Renewing or reenrolling certificate](#renewing-or-reenrolling-certificate)\n* [Troubleshooting](#troubleshooting)\n\n## Prerequisites\n\nPrerequisites for building and using ncm-issuer:\n\n* [NCM](https://www.nokia.com/networks/products/pki-authority-with-netguard-certificate-manager/) release 23 or later,\n* [Kubernetes](https://kubernetes.io) version 1.24 - 1.33,\n* [cert-manager](https://cert-manager.io/) version 1.0.0 or later,\n* Kubernetes container runtime like Docker, containerd or CRI-O,\n* [Helm](https://helm.sh/docs/intro/install/) v3.\n\n### Installing using Helm\n\nThe easiest way to install ncm-issuer in Kubernetes cluster is to use Helm. The image will be automatically downloaded from public repository.\n\n\u003cimg src=\"./assets/installation.gif\" alt=\"installation\"/\u003e\n\nInstall ncm-issuer using the command:\n\n  ```bash\n  $ helm install \\\n  ncm-issuer \\\n  --create-namespace --namespace ncm-issuer \\\n  helm\n  ```\n\nOn the other hand, if you did not use `git`, but downloaded the packaged version of ncm-issuer use:\n\n  ```bash\n  $ helm install \\\n  ncm-issuer \\\n  --create-namespace --namespace ncm-issuer \\\n  ncm-issuer/charts/ncm-issuer\n  ```\n\n#### Using own (local or remote) registry\n\nIn case you want to use your own registry, just change the value pointing to a specific registry\nin the `values.yaml` file in directory that contains Helm files. Then just repeat the steps\nmentioned above.\n\n  ```bash\n  sed -i \"s|docker.io/misiektoja|\u003cyour-registry\u003e|g\" values.yaml\n  ```\n\n**:warning: Warning:** Using this command will also change the registry pointing to the image location of troubleshooting sidecar.\nBear this in mind if you want to use sidecar as well.\n\nHowever, if you do not know where to get image from, because you cloned the repository\njust use the command:\n\n  ```bash\n  $ make docker-build\n  ```\n\nor (if you also want to save image)\n\n  ```bash\n  $ make docker-save\n  ```\n\nSaved image should appear in the path `./builds/ncm-issuer-images/`.\n\n### Configuration\n\nTo make the ncm-issuer work properly, it is necessary to create few Kubernetes secrets\nthat contains credentials to NCM REST API and TLS configuration.\n\n\u003cimg src=\"./assets/configuration.gif\" alt=\"configuration\" /\u003e\n\n#### NCM REST API credentials\n\n  ```bash\n  $ kubectl create secret generic \\\n  \u003csecret-name\u003e \\\n  -n \u003cnamespace\u003e \\\n  --from-literal=username=\u003cusername\u003e \\\n  --from-literal=usrPassword=\u003cpassword\u003e\n  ```\n\n#### TLS without client authentication\n\n  ```bash\n  $ kubectl create secret generic \\\n  \u003csecret-name\u003e \\\n  -n \u003cnamespace\u003e \\\n  --from-file=cacert=\u003cca-for-tls.pem\u003e\n  ```\n\n#### TLS with client authentication\n\n  ```bash\n  $ kubectl create secret generic \\\n  \u003csecret-name\u003e \\\n  -n \u003cnamespace\u003e \\\n  --from-file=cacert=\u003cca-for-tls.pem\u003e \\\n  --from-file=key=\u003cclient-auth-pkey.pem\u003e \\\n  --from-file=cert=\u003cclient-auth-cert.pem\u003e\n  ```\n\nTo make sure that specific secret have been created correctly, you can check this\nby using command:\n\n  ```bash\n  $ kubectl -n \u003cnamespace\u003e describe secrets \u003csecret-name\u003e\n  ```\n\n## Custom resource definitions (CRDs)\n\n### Issuer resource\n\nBelow is an example `yaml` file containing `Issuer` definition:\n\n  ```yaml\n  apiVersion: certmanager.ncm.nokia.com/v1\n  kind: Issuer\n  metadata:\n    name: example-ncm-issuer\n    namespace: ncm-ns\n  spec:\n    # caName or caID is always required.\n    caName: ncm-ca\n    caID: e1DefAscx\n    provisioner:\n      # mainAPI is always required.\n      mainAPI: https://nokia-ncm.local\n      backupAPI: https://nokia-backup-ncm.local\n      httpClientTimeout: 10s\n      healthCheckerInterval: 1m\n      # authRef is always required.\n      authRef:\n        name: ncm-rest-auth\n        namespace: ncm-ns\n      tlsRef:\n        name: ncm-tls\n        namespace: ncm-ns\n    profileId: \"101\"\n    useProfileIDForRenew: true\n    reenrollmentOnRenew: true\n    noRoot: true\n    chainInSigner: false\n    onlyEECert: true\n  ```\n\n**:warning: Warning:** With release `1.1.0-1.1.0` the name of some fields in `Issuer` has changed, but old names are\nstill supported and can be used (this applies to: `CASNAME`, `CASHREF`, `ncmSERVER`, `ncmSERVER2`, `secretName`,\n`tlsSecretName`, `authNameSpace`).\n\n### ClusterIssuer resource\n\nWith the `ClusterIssuer`, the definition does not differ from that presented\nwith `Issuer`, and the only differences are in the field `kind` and the non-existence of field\n`.metadata.namespace` due to `Cluster` scope reasons.\n\n  ```yaml\n  apiVersion: certmanager.ncm.nokia.com/v1\n  kind: ClusterIssuer\n  metadata:\n    name: example-ncm-clusterissuer\n  spec:\n    ...\n  ```\n\n### Issuer and ClusterIssuer fields overview\n\n| Field                                     | Description                                                                                                                                                                                                                                                                     | Supported from |\n|:------------------------------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|:--------------:|\n| `.spec.caName`                            | Name of an existing CA in the NCM, which will be used to issue certificates (required if `.spec.caID` is not specified)                                                                                                                                                         |  1.1.0-1.1.0   |\n| `.spec.caID`                              | Unique HREF identifier for existing CA in the NCM, which will be used to issue certificates (required if `.spec.caName` is not specified)                                                                                                                                       |  1.1.0-1.1.0   |\n| `.spec.provisioner.mainAPI`               | The URL to the main NCM REST API (always required)                                                                                                                                                                                                                              |  1.1.0-1.1.0   |\n| `.spec.provisioner.backupAPI`             | The URL to the backup NCM REST API in case of the lack of connection to the main one                                                                                                                                                                                            |  1.1.0-1.1.0   |\n| `.spec.provisioner.httpClientTimeout`     | Maximum amount of time that the HTTP client will wait for a response from NCM REST API before aborting the request                                                                                                                                                              |  1.1.0-1.1.0   |\n| `.spec.provisioner.healthCheckerInterval` | The time interval between each NCM REST API health check                                                                                                                                                                                                                        |  1.1.0-1.1.0   |\n| `.spec.provisioner.authRef`               | Reference to a Secret containing the credentials (user and password) needed for making requests to NCM REST API (always required)                                                                                                                                               |  1.1.0-1.1.0   |\n| `.spec.provisioner.tlsRef`                | Reference to a Secret containing CA bundle used to verify connections to the NCM REST API. If the secret reference is not specified and selected protocol is HTTPS, InsecureSkipVerify will be used. Otherwise, TLS or mTLS connection will be used, depending on provided data |  1.1.0-1.1.0   |\n| `.spec.reenrollmentOnRenew`               | Determines whether during renewal, certificate should be re-enrolled instead of renewed                                                                                                                                                                                         |  1.0.1-1.0.0   |\n| `.spec.profileId`                         | Entity profile ID in NCM, optional; needs to be in double quotes                                                                                                                                                                                                                |  1.0.1-1.0.0   |\n| `.spec.noRoot`                            | Determines whether issuing CA certificate should be included in issued certificate CA field (ca.crt) instead of root CA certificate                                                                                                                                             |  1.0.1-1.0.0   |\n| `.spec.chainInSigner`                     | Determines whether certificate chain should be included in issued certificate CA field (ca.crt - root CA certificate + intermediate CA certificates + singing CA certificate)                                                                                                   |  1.0.3-1.0.2   |\n| `.spec.onlyEECert`                        | Determines whether only end-entity certificate should be included in issued certificate TLS field (tls.crt)                                                                                                                                                                     |  1.0.3-1.0.2   |\n\n**:x: Deprecated:** The following fields are not recommended to be used anymore!\n\n| Field                 | Description                                                                                                      | Supported from |\n|:----------------------|:-----------------------------------------------------------------------------------------------------------------|:--------------:|\n| `.spec.CASNAME`       | Name of an existing CA in the NCM, which will be used to issue certificates                                      |  1.0.1-1.0.0   |\n| `.spec.CASHREF`       | Unique HREF identifier for existing CA in the NCM, which will be used to issue certificates                      |  1.0.1-1.0.0   |\n| `.spec.ncmSERVER`     | The URL to the main NCM REST API                                                                                 |  1.0.1-1.0.0   |\n| `.spec.ncmSERVER2`    | The URL to the backup NCM REST API in case of the lack of connection to the main one                             |  1.0.3-1.0.2   |\n| `.spec.SecretName`    | The name of Secret which contains the credentials (user and password) needed for making requests to NCM REST API |  1.0.1-1.0.0   |\n| `.spec.authNameSpace` | The name of namespace in which Secret to NCM REST API credentials can be found                                   |  1.0.1-1.0.0   |\n| `.spec.tlsSecretName` | The name of Secret which contains CA bundle used to verify connections to the NCM REST API                       |  1.0.1-1.0.0   |\n\n## Usage\n\n### Create an Issuer\n\nOnce the deployment is up and running, you are ready to create your first `Issuer`!\n\n\u003cimg src=\"./assets/creating-issuer.gif\" alt=\"creating-issuer\" /\u003e\n\nThe following is an example `Issuer` created for the namespace `example-ncm-ns`:\n\n  ```bash\n  $ cat \u003c\u003c EOF | kubectl apply -f -\n  apiVersion: certmanager.ncm.nokia.com/v1\n  kind: Issuer\n  metadata:\n    name: example-ncm-issuer\n    namespace: example-ncm-ns\n  spec:\n    caName: ncm-ca\n    provisioner:\n      mainAPI: https://nokia-ncm.local\n      authRef:\n        name: ncm-rest-auth\n        namespace: example-ncm-ns\n  EOF\n  ```\n\nAfter creating the `Issuer`, we should now be able to check its status:\n\n  ```bash\n  $ kubectl get ncmissuers -n example-ncm-ns\n  NAME                 AGE   READY   REASON     MESSAGE\n  example-ncm-issuer   3s    True    Verified   Signing CA verified and ready to sign certificates\n  ```\n\nThe above output tells us that our `Issuer` is ready to sign certificates!\n\n### Signing certificate\n\nOnce the `Issuer` was successfully created, it is now time to sign the first certificate:\n\n\u003cimg src=\"./assets/signing-certificate.gif\" alt=\"signing-certificate\" /\u003e\n\n  ```bash\n  $ cat \u003c\u003c EOF | kubectl apply -f -\n  apiVersion: cert-manager.io/v1\n  kind: Certificate\n  metadata:\n    name: example-ncm-certificate\n    namespace: example-ncm-ns\n  spec:\n    duration: 4382h\n    commonName: example-ncm-certificate-nokia-ncm.local\n    dnsNames:\n    - example-ncm-certificate-nokia-ncm.local\n    subject:\n      countries:\n      - PL\n      organizationalUnits:\n      - Security\n      organizations:\n      - Nokia\n    usages:\n    - server auth\n    - data encipherment\n    secretName: example-ncm-certificate-nokia-ncm-tls\n    issuerRef:\n      group: certmanager.ncm.nokia.com\n      kind: Issuer\n      name: example-ncm-issuer\n  EOF\n  ```\n\nNOTE: Duration parameter is ignored, unless NCM release \u003e= `24.11` (with REST API \u003e= `1.13`) is used and CA's `set-validity-period` policy module's `Overwrite Old` parameter is set to false (in such case the duration parameter is taken into consideration for new enrollments, re-enrollments and renewals).\n\nThen we can check the status of our newly issued certificate:\n\n  ```bash\n  $ kubectl get certificates -n example-ncm-ns\n  NAME                      READY   SECRET                                  AGE\n  example-ncm-certificate   True    example-ncm-certificate-nokia-ncm-tls   17s\n  ```\n\nand whether it has corresponding Secret referenced:\n\n  ```bash\n  $ kubectl get secrets -n example-ncm-ns\n  NAME                                    TYPE                                  DATA   AGE\n  default-token-g2f47                     kubernetes.io/service-account-token   3      18m\n  example-ncm-certificate-details         Opaque                                1      22s\n  example-ncm-certificate-nokia-ncm-tls   kubernetes.io/tls                     3      22s\n  ```\n\nAdditionally, in NCM GUI we can also find our newly issued certificate.\n\n### Renewing or re-enrolling certificate\n\nWhen it comes to renewing or re-enrolling certificates, ncm-issuer will take care of this and\ndo it before the certificate expires (the renewal grace period\ndepends on the defined values in `Certificate` resource).\n\nYou can define what operation ncm-issuer should perform in such a case by\nsetting certain PK rotation policy in `Certificate` resource.\n\n|               Field               |  Operation   |             Value             |\n|:---------------------------------:|:------------:|:-----------------------------:|\n| `.spec.privateKey.rotationPolicy` | Re-enrollment |           \"Always\"            |\n| `.spec.privateKey.rotationPolicy` |   Renewal    | \"Never\" or not even specified |\n\n**:loudspeaker: Attention:** There is also an option for enforcing the re-enrollment on\nrenewal in the definition of `Issuer` or `ClusterIssuer` resource. To do this simply set `.spec.reenrollmentOnRenew`\nto **true** in `Issuer` or `ClusterIssuer` definition.\n\nHowever, you can also trigger renewal or re-enrolling operation manually using one of the commands below.\n\nIn case you have cert-manager kubectl plugin:\n\n  ```bash\n  $ kubectl cert-manager renew \u003ccertificate\u003e -n \u003cnamespace\u003e\n  ```\n\nIn case you use cmctl:\n\n  ```bash\n  $ cmctl renew \u003ccertificate\u003e -n \u003cnamespace\u003e\n  ```\n\n## Troubleshooting\n\nIn case of any problem, besides checking the status of created resources,\nyou can also check the `ncm-issuer` pod logs:\n\n  ```bash\n  $ kubectl -n ncm-issuer logs -f `kubectl get pods -A -l app=ncm-issuer -o jsonpath='{.items[0].metadata.name}'`\n  ```\n\nIf you deployed troubleshooting sidecar as well, you can check the `ncm-issuer` pod logs this way:\n\n  ```bash\n  $ kubectl -n ncm-issuer logs -c ncm-issuer -f `kubectl get pods -A -l app=ncm-issuer -o jsonpath='{.items[0].metadata.name}'`\n  ```\n\nIn the case you want to increase logging verbosity level, change the `logging.logLevel` in `values.yaml` to\nthe desired value and update your deployment. To get all possible log messages, simply set the\n`logging.logLevel` to **3**, you can also additionally change the `logging.stacktraceLevel` to\n`error`.\n\nThere is also the possibility of using sidecar for troubleshooting purposes - just change the value of\n`sidecar.enabled` to **true** in `values.yaml` and update your deployment.\n\n\u003cp align=\"right\"\u003e(\u003ca href=\"#top\"\u003eback to top\u003c/a\u003e)\u003c/p\u003e\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fncm-issuer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fnokia%2Fncm-issuer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fnokia%2Fncm-issuer/lists"}