Merge pull request #30 from BbqGamer/release-1.0.4

Add github release actions - mkdocs and helm on gh-pages

.github/workflows/release.yml

@@ -28,4 +28,72 @@ jobs:
           context: .
           file: ./Dockerfile
           push: true
-          tags: ${{ secrets.DOCKER_USERNAME }}/ncm-issuer:latest,${{ secrets.DOCKER_USERNAME }}/ncm-issuer:${{ env.TAG }}
+          tags: ${{ secrets.DOCKER_USERNAME }}/ncm-issuer:latest,${{ secrets.DOCKER_USERNAME }}/ncm-issuer:${{ env.TAG }}
+
+  pages:
+    name: Build mkdocs and helm charts
+    runs-on: ubuntu-latest
+    steps:
+    - name: Checkout code
+      uses: actions/checkout@v4
+      with:
+        ref: main
+
+    - name: Install Python
+      uses: actions/setup-python@v2
+      with:
+        python-version: 3.x
+
+    - name: Install MkDocs and dependencies
+      run: |
+        pip install mkdocs-material mkdocs-awesome-pages-plugin
+
+    - name: Create release notes file
+      run: |
+        mkdir -p ./docs/release-notes
+        release_file=./docs/release-notes/${{ github.event.release.tag_name }}.md
+        echo -e "---\ntitle: ${{ github.event.release.name }}\n---\n" > $release_file
+        cat << "EOF" >> $release_file
+        ${{ github.event.release.body }}
+        EOF
+        sed -i "s|nav:|nav:\n    - ${{ github.event.release.name }}.md|g" docs/release-notes/.pages
+  
+    - uses: stefanzweifel/git-auto-commit-action@v5
+      with:
+        commit_message: Write release notes to documentation
+        file_pattern: './docs/release-notes'
+        skip_checkout: true
+
+    - name: Build MkDocs Configuration
+      run: |
+        mkdocs build        
+
+    - name: Package charts
+      run: helm package helm/
+
+    - name: Checkout to gh-pages
+      uses: actions/checkout@v4
+      with:
+        ref: gh-pages
+        clean: false
+
+    - name: Move files to the pages gh-pages
+      run: |
+        mkdir -p ./docs && rm -rf ./docs/* && mv ./site/* ./docs
+        mkdir -p ./charts && mv ./*.tgz ./charts
+
+    - name: Index charts
+      run: helm repo index ./charts
+
+    - uses: stefanzweifel/git-auto-commit-action@v5
+      with:
+        commit_message: Update documentation
+        file_pattern: './docs'
+        skip_checkout: true
+
+    - uses: stefanzweifel/git-auto-commit-action@v5
+      with:
+        commit_message: Update helm charts 
+        file_pattern: './charts'
+        skip_checkout: true
+

docs/documentation/.pages

@@ -0,0 +1,8 @@
+nav:
+    - installation.md
+    - configuration.md
+    - CRDs
+    - certificates
+    - metrics
+    - tutorials
+    - troubleshooting.md

docs/documentation/CRDs/.pages

@@ -0,0 +1,3 @@
+nav:
+    - issuer.md
+    - cluster-issuer.md

docs/documentation/CRDs/cluster-issuer.md

@@ -0,0 +1,46 @@
+# ClusterIssuer
+
+With the `ClusterIssuer`, the definition does not differ from that presented
+with `Issuer`, and the only differences are in the field `kind` and the non-existence of field
+`.metadata.namespace` due to `Cluster` scope reasons.
+
+## Resource definition
+
+Below is an example `yaml` file containing `ClusterIssuer` definition:
+
+  ```yaml title="clusterissuer.yaml"
+  apiVersion: certmanager.ncm.nokia.com/v1
+  kind: ClusterIssuer
+  metadata:
+    name: example-ncm-clusterissuer
+  spec:
+    caName: ncm-ca
+    caID: e1DefAscx
+    provisioner:
+      mainAPI: https://nokia-ncm.local
+      backupAPI: https://nokia-backup-ncm.local
+      httpClientTimeout: 10s
+      healthCheckerInterval: 1m
+      authRef:
+        name: ncm-rest-auth
+        namespace: ncm-ns
+      tlsRef:
+        name: ncm-tls
+        namespace: ncm-ns
+    profileId: "101"
+    useProfileIDForRenew: true
+    reenrollmentOnRenew: true
+    noRoot: true
+    chainInSigner: false
+    onlyEECert: true
+  ```
+
+!!! warning
+    With release `1.1.0-1.1.0` the name of some fields in `Issuer` has changed, but old names are
+    still supported and can be used (this applies to: `CASNAME`, `CASHREF`, `ncmSERVER`, `ncmSERVER2`, `secretName`,
+    `tlsSecretName`, `authNameSpace`), but they are not recommended to be used anymore.
+
+## Fields description
+
+As mentioned above, the `ClusterIssuer` differs practically in nothing from the `Issuer`, so the description of
+`Issuer` fields and their usage is also correct for it: [issuer fields description](issuer.md#fields-description).

docs/documentation/CRDs/issuer.md

@@ -0,0 +1,87 @@
+# Issuer
+
+The first thing you need to configure and create after installing ncm-issuer is `Issuer` or `ClusterIssuer`. 
+The `Issuer` or `ClusterIssuer` is considered as a representative of an existing certificate authority (CA) 
+in the NCM that will issue certificates using it.
+
+## Resource definition
+
+Below is an example `yaml` file containing `Issuer` definition:
+
+  ```yaml title="issuer.yaml"
+  apiVersion: certmanager.ncm.nokia.com/v1
+  kind: Issuer
+  metadata:
+    name: example-ncm-issuer
+    namespace: ncm-ns
+  spec:
+    caName: ncm-ca
+    caID: e1DefAscx
+    provisioner:
+      mainAPI: https://nokia-ncm.local
+      backupAPI: https://nokia-backup-ncm.local
+      httpClientTimeout: 10s
+      healthCheckerInterval: 1m
+      authRef:
+        name: ncm-rest-auth
+        namespace: ncm-ns
+      tlsRef:
+        name: ncm-tls
+        namespace: ncm-ns
+    profileId: "101"
+    useProfileIDForRenew: true
+    reenrollmentOnRenew: true
+    noRoot: true
+    chainInSigner: false
+    onlyEECert: true
+  ```
+
+!!! warning
+    With release `1.1.0-1.1.0` the name of some fields in `Issuer` has changed, but old names are
+    still supported and can be used (this applies to: `CASNAME`, `CASHREF`, `ncmSERVER`, `ncmSERVER2`, `secretName`,
+    `tlsSecretName`, `authNameSpace`), but they are not recommended to be used anymore.
+
+## Fields description
+
+The number next to the label icon indicates from which version the fields are supported.
+
+> :material-tag: [1.1.0-1.1.0](../../release-notes/1.1.0.md)
+
+| Field                                     | Description                                                                                                                                                                                                                                                                  |
+|:------------------------------------------|:-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.spec.caName`                            | Name of an existing CA in the NCM, which will be used to issue certificates                                                                                                                                                                                                  |
+| `.spec.caID`                              | Unique href (or ID) identifier for existing CA in the NCM, which will be used to issue certificates                                                                                                                                                                          |
+| `.spec.provisioner.mainAPI`               | The URL to the main NCM API endpoint                                                                                                                                                                                                                                         |
+| `.spec.provisioner.backupAPI`             | The URL to the backup NCM API endpoint in case of the lack of connection to the main one                                                                                                                                                                                     |
+| `.spec.provisioner.httpClientTimeout`     | Maximum amount of time that the HTTP client will wait for a response from NCM API before aborting the request                                                                                                                                                                |
+| `.spec.provisioner.healthCheckerInterval` | The time interval between each NCM API health check                                                                                                                                                                                                                          |
+| `.spec.provisioner.authRef`               | Reference to a `secret` containing the credentials (user and password) needed for making requests to NCM API                                                                                                                                                                 |
+| `.spec.provisioner.tlsRef`                | Reference to a `secret` containing CA bundle used to verify connections to the NCM 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 |
+
+> :material-tag: [1.0.3-1.0.2](../../release-notes/1.0.3.md)
+
+| Field                 | Description                                                                                                                                                                     |
+|:----------------------|:--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|
+| `.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) |
+| `.spec.onlyEECert`    | Determines whether only end-entity certificate should be included in issued certificate TLS field (`tls.crt`)                                                                   |
+
+> :material-tag: [1.0.1-1.0.0](../../release-notes/1.0.1.md)
+
+| Field                       | Description                                                                                                                           |
+|:----------------------------|:--------------------------------------------------------------------------------------------------------------------------------------|
+| `.spec.reenrollmentOnRenew` | Determines whether during renewal, certificate should be re-enrolled instead of renewed                                               |                                                                                                                                                                         
+| `.spec.profileId`           | Entity profile ID in NCM                                                                                                              |                                                                                                                                                                                                                                           
+| `.spec.noRoot`              | Determines whether issuing CA certificate should be included in issued certificate CA field (`ca.crt`) instead of root CA certificate | 
+
+!!! Danger
+    The following fields are not recommended to be used anymore!
+
+    | Field                 | Description                                                                                                        |
+    |:----------------------|:-------------------------------------------------------------------------------------------------------------------|
+    | `.spec.CASNAME`       | Name of an existing CA in the NCM, which will be used to issue certificates                                        |
+    | `.spec.CASHREF`       | Unique HREF identifier for existing CA in the NCM, which will be used to issue certificates                        |
+    | `.spec.ncmSERVER`     | The URL to the main NCM API endpoint                                                                               |
+    | `.spec.ncmSERVER2`    | The URL to the backup NCM API endpoint in case of the lack of connection to the main one                           |
+    | `.spec.SecretName`    | The name of `secret` which contains the credentials (user and password) needed for making requests to NCM REST API |
+    | `.spec.authNameSpace` | The name of namespace in which `secret` to NCM API credentials can be found                                        |
+    | `.spec.tlsSecretName` | The name of `secret` which contains CA bundle used to verify connections to the NCM API                            |

docs/documentation/certificates/certificates.md

@@ -0,0 +1,32 @@
+# Renewing or re-enrolling
+
+When it comes to renewing or re-enrolling certificates, ncm-issuer will take care of this and
+do it before the certificate expires (the renewal grace period
+depends on the defined values in `Certificate` resource).
+
+You can define what operation ncm-issuer should perform in such a case by
+setting certain PK rotation policy in `Certificate` resource.
+
+|               Field               |   Operation   |             Value             |
+|:---------------------------------:|:-------------:|:-----------------------------:|
+| `.spec.privateKey.rotationPolicy` | re-enrollment |           "Always"            |
+| `.spec.privateKey.rotationPolicy` |    renewal    | "Never" or not even specified |
+
+!!! tip
+    There is also an option for enforcing the re-enrollment on
+    renewal in the definition of `Issuer` or `ClusterIssuer` resource. To do this simply set `.spec.reenrollmentOnRenew`
+    to **true** in `Issuer` or `ClusterIssuer` definition.
+
+However, you can also trigger renewal or re-enrolling operation manually using one of the commands below.
+
+In case you have cert-manager kubectl plugin:
+
+  ```bash
+  kubectl cert-manager renew <certificate> -n <namespace>
+  ```
+
+In case you use cmctl:
+
+  ```bash
+  cmctl renew <certificate> -n <namespace>
+  ```

docs/documentation/configuration.md

@@ -0,0 +1,46 @@
+# Configuration
+
+To make the ncm-issuer work properly, it is necessary to create few Kubernetes secrets
+that contains credentials to NCM REST API and optional TLS configuration.
+
+<figure markdown>
+  ![installation](../assets/configuration.gif)
+</figure>
+
+## NCM REST API credentials
+
+  ```bash
+  kubectl create secret generic \
+  <secret-name> \
+  -n <namespace> \
+  --from-literal=username=<username> \
+  --from-literal=usrPassword=<password>
+  ```
+
+## TLS without client authentication
+
+  ```bash
+  kubectl create secret generic \
+  <secret-name> \
+  -n <namespace> \
+  --from-file=cacert=<ca-for-tls.pem>
+  ```
+
+## TLS with client authentication
+
+  ```bash
+  kubectl create secret generic \
+  <secret-name> \
+  -n <namespace> \
+  --from-file=cacert=<ca-for-tls.pem> \
+  --from-file=key=<client-auth-pkey.pem> \
+  --from-file=cert=<client-auth-cert.pem>
+  ```
+
+!!! tip
+    To make sure that specific secret have been created correctly, you can check this
+    by using command:
+
+    ```bash
+    kubectl -n <namespace> describe secrets <secret-name>
+    ```