docs/sections/external-provider.rst

   1 .. This work is licensed under a Creative Commons Attribution 4.0 International License.
   2 .. http://creativecommons.org/licenses/by/4.0
   3 .. Copyright 2020 NOKIA
   4
   5 K8s external provider
   6 ==============================
   7
   8 General information
   9 ------------------------------
  10
  11 Cert Service K8s external provider is a part of certificate distribution infrastructure in ONAP.
  12 The main functionality of the provider is to forward Certificate Signing Requests (CSRs) created by cert-mananger (https://cert-manager.io) to CertServiceAPI.
  13
  14 Additional information can be found on a dedicated page:  https://wiki.onap.org/display/DW/CertService+and+K8s+Cert-Manager+integration.
  15
  16
  17 CMPv2 Issuer
  18 ------------------------------
  19
  20 In order to be able to request a certificate via K8s external provider a *CMPv2Issuer* CRD (Customer Resource Definition) instance has to be created.
  21
  22 It is important to note that the attribute *kind* has to be set to **CMPv2Issuer**, all other attributes can be set as needed.
  23
  24 NOTE: a default instance of CMPv2Issuer is created when installing ONAP via OOM deployment (values can also be adjusted as needed)
  25
  26 Here is an example of a *CMPv2Issuer*:
  27
  28 .. code-block:: yaml
  29
  30   apiVersion: certmanager.onap.org/v1
  31   kind: CMPv2Issuer
  32   metadata:
  33     name: cmpv2-issuer
  34     namespace: onap
  35   spec:
  36     url: https://oom-cert-service:8443
  37     healthEndpoint: actuator/health
  38     certEndpoint: v1/certificate
  39     caName: RA
  40     certSecretRef:
  41       name: cmpv2-issuer-secret
  42       certRef: cmpv2Issuer-cert.pem
  43       keyRef: cmpv2Issuer-key.pem
  44       cacertRef: cacert.pem
  45
  46
  47 Certificate enrolling
  48 ------------------------------
  49
  50 In order to request a certificate a K8s *Certificate* CRD (Custom Resource Definition) has to be created.
  51
  52 It is important that in the section issuerRef following attributes have correct values:
  53   - group: **certmanager.onap.org**
  54   - kind: **CMPv2Issuer**
  55
  56 After *Certificate* CRD has been placed cert manager will send a *CSR* (Certificate Sign Request) to CA (Certificate Authority) via K8s external provider.
  57 Signed certificate as well as trust anchor (CA root certificate) will be stored in the K8s *secret* specified in *Certificate* CRD (see secretName attribute).
  58
  59 By default certificates will be stored in PEM format. It is possible to get certificates also in JKS and P12 format - see example below - more information can be found on official cert manager page.
  60
  61 The following SANs types are supported: DNS names, IPs, URIs, emails.
  62
  63 Here is an example of a *Certificate*:
  64
  65 .. code-block:: yaml
  66
  67   apiVersion: cert-manager.io/v1
  68   kind: Certificate
  69   metadata:
  70     name: certificate_name
  71     namespace: onap
  72   spec:
  73     # The secret name to store the signed certificate
  74     secretName: secret_name
  75     # Common Name
  76     commonName: certissuer.onap.org
  77     subject:
  78       organizations:
  79         - Linux-Foundation
  80       countries:
  81         - US
  82       localities:
  83         - San-Francisco
  84       provinces:
  85         - California
  86       organizationalUnits:
  87         - ONAP
  88     # SANs
  89     dnsNames:
  90       - localhost
  91       - certissuer.onap.org
  92     ipAddresses:
  93       - "127.0.0.1"
  94     uris:
  95       - onap://cluster.local/
  96     emailAddresses:
  97       - onap@onap.org
  98     # The reference to the CMPv2 issuer
  99     issuerRef:
 100       group: certmanager.onap.org
 101       kind: CMPv2Issuer
 102       name: cmpv2-issuer
 103     # Section keystores is optional and defines in which format certificates will be stored
 104     # If this section is omitted than only PEM format will be present in the secret
 105     keystores:
 106         jks:
 107           create: true
 108           passwordSecretRef: # Password used to encrypt the keystore
 109             name: certservice-key
 110             key: key
 111         pkcs12:
 112           create: true
 113           passwordSecretRef: # Password used to encrypt the keystore
 114             name: certservice-key
 115             key: key
 116
 117
 118 Here is an example of generated *secret* containing certificates:
 119
 120 .. code-block:: yaml
 121
 122     Name:         secret_name
 123     Namespace:    onap
 124     Labels:       <none>
 125     Annotations:  cert-manager.io/alt-names: localhost,certissuer.onap.org
 126                   cert-manager.io/certificate-name: certificate_name
 127                   cert-manager.io/common-name: certissuer.onap.org
 128                   cert-manager.io/ip-sans:
 129                   cert-manager.io/issuer-group: certmanager.onap.org
 130                   cert-manager.io/issuer-kind: CMPv2Issuer
 131                   cert-manager.io/issuer-name: cmpv2-issuer-onap
 132                   cert-manager.io/uri-sans:
 133
 134     Type:  kubernetes.io/tls
 135
 136     Data
 137     ====
 138     tls.crt:         1675 bytes  <-- Certificate (PEM)
 139     tls.key:         1679 bytes  <-- Private Key (PEM)
 140     truststore.jks:  1265 bytes  <-- Trusted anchors (JKS)
 141     ca.crt:          1692 bytes  <-- Trusted anchors (PEM)
 142     keystore.jks:    3786 bytes  <-- Certificate and Private Key (JKS)
 143     keystore.p12:    4047 bytes  <-- Certificate and Private Key (P12)
 144
 145
 146