Add documentation to Charmhub

Signed-off-by: gatici <[email protected]>
canonical · Aug 16, 2023 · 0c6c23f · 0c6c23f
1 parent dc611fe
commit 0c6c23f
Show file tree

Hide file tree

Showing 12 changed files with 342 additions and 8 deletions.
diff --git a/README.md b/README.md
@@ -1,4 +1,4 @@
-# self-signed-certificates-operator
+# Self Signed Certificates Operator
 
 An operator to provide self-signed X.509 certificates to your charms.
 
@@ -15,16 +15,63 @@ This charm is useful when developing charms or when deploying charms in non-prod
 
 ## Usage
 
-To use the `self-signed-certificates` operator and provide certificates to your charm, your charm
-needs to support the `tls-certificates` interface.
+Bootstrap a Kubernetes (e.g. [Multipass-based MicroK8s](https://discourse.charmhub.io/t/charmed-environment-charm-dev-with-canonical-multipass/8886)) and create a new model using Juju >= 3.1:
 
-```console
+```shell
+juju add-model certificates
 juju deploy self-signed-certificates
-juju deploy <your charm>
-juju relate self-signed-certificates <your charm>
+juju deploy self-signed-certificates --channel edge
+```
+
+To confirm the deployment, you can run:
+
+```shell
+juju status --watch 1s
+```
+
+If required, you can remove the application by running:
+
+```shell
+juju remove-application self-signed-certificates
+```
+
+If required, you can remove the deployment completely by running:
+
+```shell
+juju destroy-model certificates
+```
+
+## Integrations
+
+This charm provides `tls-certificates` interface.  To use the `self-signed-certificates` operator and provide certificates to another charm, the other charm needs to require the `tls-certificates` interface.
+
+```shell
+juju relate self-signed-certificates <your charm which needs tls certificates>
+```
+
+The relation status is shown by running following command:
+
+```shell
+juju status --relations
+```
+
+If the relation is established, the following output is expected:
+
+```shell
+Relation provider                      Requirer                             Interface                Type     
+self-signed-certificates:certificates  amf:certificates                     tls-certificates         regular
 ```
 
 ## Get the certificates issued by the charm
-```bash
+
+This charm supports single action `get-issued-certificates` which shows all the issued certificates.
+
+```shell
 juju run self-signed-certificates/leader get-issued-certificates
 ```
+
+The above command returns the task number and the task output is shown by running:
+
+```shell
+juju show-task <task number>
+```
diff --git a/docs/explanation/e-configure.md b/docs/explanation/e-configure.md
@@ -0,0 +1,47 @@
+# Set the operator configuration options
+
+The following charm configuration options are set to desired values if needed.
+
+- ca-common-name
+- root-ca-validity
+- certificate-validity
+
+## Setting the configuration
+
+The charm configuration are set by running following commands:
+
+```shell
+juju config self-signed-certificates root-ca-validity=180
+juju config self-signed-certificates ca-common-name=mycompany.com
+juju config self-signed-certificates certificate-validity=90
+```
+
+The updated charm configuration is displayed by running following command:
+```shell
+juju config self-signed-certificates
+```
+
+The command output is similar to following:
+
+```yaml
+charm: self-signed-certificates
+settings: 
+  ca-common-name: 
+    default: self-signed-certificates-operator
+    description: Common name to be used by the Certificate Authority.
+    source: user
+    type: string
+    value: mycompany.com
+  certificate-validity: 
+    default: 365
+    description: Certificate validity (in days).
+    source: user
+    type: int
+    value: 90
+  root-ca-validity: 
+    default: 365
+    description: RootCA certificate validity (in days).
+    source: user
+    type: int
+    value: 180
+```
diff --git a/docs/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md
@@ -0,0 +1,28 @@
+# Interfaces/Endpoints
+
+This charm provides `tls-certificates` interface.  To use the `self-signed-certificates` operator and provide certificates to another charm, the other charm needs to require the `tls-certificates` interface.
+
+## Using tls-certificates interface
+
+```shell
+juju relate self-signed-certificates <your charm which needs tls certificates>
+```
+
+The relation status is shown by running following command:
+
+```shell
+juju status --relations
+```
+
+If the relation is established, the following output is expected:
+
+```shell
+Relation provider                      Requirer                             Interface                Type     
+self-signed-certificates:certificates  amf:certificates                     tls-certificates         regular
+```
+
+To remove a relation:
+
+```shell
+juju remove-relation self-signed-certificates <other-application>
+```
diff --git a/docs/how-to/h-manage-app.md b/docs/how-to/h-manage-app.md
@@ -0,0 +1,16 @@
+# Manage Self Signed Certificates Operator
+
+## Relate with other applications using `tls-certificates` interface
+
+Relations with other applications are supported via the "[tls-certificates](hhttps://charmhub.io/self-signed-certificates/integrations)" interface. Please check [Relate Self Signed Certificates Operator with other applications](/t/self-signed-x-509-certificates-explanations-interface-endpoints/11593?channel=edge).
+
+## Deploy Application
+
+In order to deploy the application, please follow the guide [Deploy Self Signed Certificates Operator](/t/self-signed-x-509-certificates-tutorial-deploy/11596?channel=edge)
+
+## Remove Application
+
+The application is removed by running following command:
+```shell
+juju remove-application self-signed-certificates
+```
diff --git a/docs/how-to/h-manage-units.md b/docs/how-to/h-manage-units.md
@@ -0,0 +1,23 @@
+# How to deploy and manage units
+
+## Basic Usage
+
+To deploy a single unit of Self Signed Certificates Operator using its default configuration
+```shell
+juju deploy self-signed-certificates --channel edge
+```
+
+The Self Signed Certificates Operator works with single replica for the moment.
+```shell
+juju deploy self-signed-certificates --channel edge -n 1.
+```
+
+## Replication
+
+Both scaling-up and scaling-down operations are performed using `juju scale-application`:
+```shell
+juju scale-application  self-signed-certificates <desired_num_of_units>
+```
+
+Note: The operator does not support multiple replicas at the moment.
+Warning: scaling-down to zero units will destroy your data!
diff --git a/docs/index.md b/docs/index.md
@@ -0,0 +1,47 @@
+The Self Signed Certificates Operator provides self-signed X.509 certificates to your charms.
+
+This charm relies on the `tls-certificates` charm relation interface. When a requirer charm inserts a Certificate Signing Request in its unit databag, the `self-signed-certificates-operator` will read it, generate a self-signed X.509 certificates and
+inserts this certificate back into the relation data.
+
+This charm [Self-Signed-Certificates-Operator](https://github.com/canonical/self-signed-certificates-operator) is useful when developing charms or when deploying charms in non-production environment on top of [Juju](https://juju.is/).
+
+## Project and community
+The Self Signed Certificates Operator is an open-source project that welcomes community contributions, suggestions, fixes and constructive feedback.
+- [Read our Code of Conduct](https://ubuntu.com/community/code-of-conduct)
+- - [Join the Discourse forum](https://discourse.charmhub.io/tag/self-signed-certificates)
+- Contribute and report bugs to [Self-Signed-Certificates-Operator](https://github.com/canonical/self-signed-certificates-operator)
+
+## In this documentation
+|                                                                                                                                                                                         |                                                                                                                                                      |
+|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------|
+| [Tutorial](/t/self-signed-x-509-certificates-tutorial-overview/11600?channel=edge) </br>  Get started - a hands-on introduction to using Self Signed X.509 Certificates for new users </br> | [How-to guides](/t/self-signed-x-509-certificates-how-to-manage-units/11594?channel=edge) </br> Step-by-step guides covering key operations and common tasks    |
+| [Reference](https://charmhub.io/self-signed-certificates/actions?channel=edge) </br> Technical information - specifications, APIs, architecture                                         | [Explanation](/t/self-signed-x-509-certificates-explanations-interface-endpoints/11593?channel=edge) </br> Concepts - discussion and clarification of key topics |
+
+# Navigation
+
+| Level | Path                      | Navlink                                                                                                |
+| ----- |---------------------------|--------------------------------------------------------------------------------------------------------|
+| 1 | tutorial                  | [Tutorial]()                                                                                           |
+| 2 | t-overview                | [1. Introduction](/t/self-signed-x-509-certificates-tutorial-overview/11600)                           |
+| 2 | t-setup-environment       | [2. Set up the environment](/t/self-signed-x-509-certificates-tutorial-setup-environment/11599)        |
+| 2 | t-deploy                  | [3. Deploy Self Signed Certificates Operator](/t/self-signed-x-509-certificates-tutorial-deploy/11596) |
+| 2 | t-get-signed-certificates | [4. Get Signed Certificates](/t/self-signed-x-509-certificates-tutorial-get-signed-certificates/11598) |
+| 1 | how-to                    | [How To]()                                                                                             |
+| 2 | h-manage-units            | [Manage units](/t/self-signed-x-509-certificates-how-to-manage-units/11594)                            |
+| 2 | h-manage-app              | [Manage application](/t/self-signed-x-509-certificates-how-to-manage-app/11595)                        |
+| 1 | reference                 | [Reference]()                                                                                          |
+| 2 | r-actions                 | [Actions](https://charmhub.io/self-signed-certificates/actions?channel=edge)                           |
+| 2 | r-configurations          | [Configurations](https://charmhub.io/self-signed-certificates/configure?channel=edge)                  |
+| 2 | r-libraries               | [Libraries](https://charmhub.io/self-signed-certificates/libraries?channel=edge)                       |
+| 2 | r-integrations            | [Integrations](https://charmhub.io/self-signed-certificates/integrations?channel=edge)                 |
+| 1 | explanation               | [Explanation]()                                                                                        |
+| 2 | e-interfaces              | [Interfaces/endpoints](/t/self-signed-x-509-certificates-explanations-interface-endpoints/11593)       |
+| 2 | e-configure               | [Configure Charm](/t/self-signed-x-509-certificates-explanations-configure/11601)                      |
+
+
+# Redirects
+
+[details=Mapping table]
+| Path | Location |
+| ---- | -------- |
+[/details]
diff --git a/docs/reference/.gitkeep b/docs/reference/.gitkeep
diff --git a/docs/tutorial/t-deploy.md b/docs/tutorial/t-deploy.md
@@ -0,0 +1,32 @@
+# Make Self Signed Certificates Operator up and running
+
+This is part of the [Self Signed X.509 Certificates Operator Tutorial](/t/self-signed-x-509-certificates-tutorial-overview/11600?channel=edge). Please refer to this page for more information and the overview of the content.
+
+## Deploy
+
+To deploy Self Signed X.509 Certificates Operator, all you need to do is run the following command, which will fetch the charm from [Charmhub](https://charmhub.io/self-signed-certificates/integrations?channel=edge) and deploy it to your model:
+
+```shell
+juju deploy self-signed-certificates --channel edge
+```
+
+Juju will now fetch self-signed-certificates operator and begin deploying it to the local MicroK8s. This process can take several minutes depending on how provisioned (RAM, CPU, etc) your machine is. You can track the progress by running:
+```shell
+juju status --watch 1s
+```
+
+This command is useful for checking the status of self-signed-certificates operator. Some of the helpful information it displays include IP addresses, ports, state, etc. The command updates the status of Self Signed Certificates Operator every second and as the application starts you can watch the status and messages of operator change. Wait until the application is ready - when it is ready, `juju status` will show:
+```
+Model  Controller          Cloud/Region        Version  SLA          Timestamp
+tutorial   microk8s-localhost  microk8s/localhost  3.1.5    unsupported  01:14:09+03:00
+
+App                       Version  Status  Scale  Charm                     Channel        Rev  Address         Exposed  Message       
+self-signed-certificates           active      1  self-signed-certificates  edge            17  10.152.183.40   no       
+      
+
+Unit                         Workload  Agent  Address      Ports  Message         
+self-signed-certificates/0*  active    idle   10.1.146.12   
+```
+To exit the screen with `juju status --watch 1s`, enter `Ctrl+c`.
+If you want to further inspect juju logs, can watch for logs with `juju debug-log`.
+More info on logging at [juju logs](https://juju.is/docs/olm/juju-logs).
diff --git a/docs/tutorial/t-get-signed-certificates.md b/docs/tutorial/t-get-signed-certificates.md
@@ -0,0 +1,25 @@
+# Get Signed Certificates
+
+This is part of the [Self Signed X.509 Certificates Operator Tutorial](/t/self-signed-x-509-certificates-tutorial-overview/11600?channel=edge). Please refer to this page for more information and the overview of the content.
+
+## Certificates
+The charm issues certificates and generated certificates are displayed by running an action named `get-issued-certificates`.
+
+### Running action to get issued certificates
+
+```shell
+juju run self-signed-certificates/<leader unit number>  get-issued-certificates
+```
+
+Running the command should output:
+```shell
+Running operation 3 with 1 task
+  - task 4 on unit-self-signed-certificates-0
+
+Waiting for task 4...
+```
+
+The task result is shown by running following command:
+```shell
+juju show-task 4
+```
diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md
@@ -0,0 +1,24 @@
+# Self Signed X.509 Certificates tutorial
+
+The Self Signed X.509 Certificates Operator provides self-signed X.509 certificates to your charms by setting up a relation with a requirer charm. This charm generates a self-signed X.509 certificates for a requirer by using Certificate Signing Request sent in the relation databag.
+
+This charm is useful when developing charms or when deploying charms in non-production environment.In this tutorial we will walk through how to:
+- Set up an environment using [Multipass](https://multipass.run/) with [MicroK8s](https://microk8s.io/) and [Juju](https://juju.is/).
+- Deploy Self Signed X.509 Certificates Operator using a single command.
+- Configuring charm
+- Setting up relations with other charms
+- Getting signed certificates
+- Managing application and units
+
+## Step-by-step guide
+
+Here’s an overview of the steps required with links to our separate tutorials that deal with each individual step:
+* [Set up the environment](/t/self-signed-x-509-certificates-tutorial-setup-environment/11599?channel=edge)
+* [Deploy Self Signed Certificates Operator](/t/self-signed-x-509-certificates-tutorial-deploy/11596?channel=edge)
+* [Configure Self Signed Certificates Operator](/t/self-signed-x-509-certificates-explanations-configure/11601?channel=edge)
+* [Managing your units](/t/self-signed-x-509-certificates-how-to-manage-units/11594/9299?channel=edge)
+* [Relate Self Signed Certificates Operator with other applications](/t/self-signed-x-509-certificates-explanations-interface-endpoints/11593?channel=edge)
+* [Get Signed Certificates](/t/self-signed-x-509-certificates-tutorial-get-signed-certificates/11598?channel=edge)
+
+# License:
+The Self Signed X.509 Certificates Operator [is distributed](https://github.com/canonical/self-signed-certificates-operator/blob/main/LICENSE) under the Apache Software License, version 2.0.
diff --git a/docs/tutorial/t-setup-environment.md b/docs/tutorial/t-setup-environment.md
@@ -0,0 +1,45 @@
+# Environment Setup
+
+This is part of the [Self Signed X.509 Certificates Operator Tutorial](/t/self-signed-x-509-certificates-tutorial-overview/11600?channel=edge). Please refer to this page for more information and the overview of the content.
+
+## Minimum requirements
+Before we start, make sure your machine meets the following requirements:
+- Ubuntu 22.04 (Jammy) or later.
+- 8GB of RAM.
+- 2 CPU threads.
+- At least 20GB of available storage.
+- Access to the internet for downloading the required snaps and charms.
+
+## Multipass environment
+[Multipass](https://multipass.run/) is a quick and easy way to launch virtual machines running Ubuntu. It uses "[cloud-init](https://cloud-init.io/)" standard to install and configure all the necessary parts automatically.
+
+Let's install Multipass from [Snap](https://snapcraft.io/multipass) and launch a new VM using "[charm-dev](https://github.com/canonical/multipass-blueprints/blob/main/v1/charm-dev.yaml)" cloud-init config:
+```shell
+sudo snap install multipass && \
+multipass launch --cpus 4 --memory 8G --disk 30G --name my-vm charm-dev # tune CPU/RAM/HDD accordingly to your needs
+```
+*Note: all 'multipass launch' params are [described here](https://multipass.run/docs/launch-command)*.
+
+Multipass [list of commands](https://multipass.run/docs/multipass-cli-commands) is short and self-explanatory, e.g. show all running VMs:
+```shell
+multipass list
+```
+
+As soon as new VM started, enter inside using:
+```shell
+multipass shell my-vm
+```
+*Note: if at any point you'd like to leave Multipass VM, enter `Ctrl+d` or type `exit`*.
+
+All the parts have been pre-installed inside VM already, like MicroK8s and Juju (the files '/var/log/cloud-init.log' and '/var/log/cloud-init-output.log' contain all low-level installation details). The Juju controller can work with different models; models host applications such as Charmed PostgreSQL K8s. Set up a specific model for Charmed PostgreSQL K8s named ‘tutorial’:
+```shell
+juju add-model tutorial
+```
+
+You can now view the model you created above by entering the command `juju status` into the command line. You should see the following:
+```
+Model     Controller  Cloud/Region        Version  SLA          Timestamp
+tutorial  charm-dev   microk8s/localhost  2.9.42   unsupported  11:56:38+01:00
+
+Model "admin/tutorial" is empty.
+```
diff --git a/metadata.yaml b/metadata.yaml
@@ -16,7 +16,7 @@ description: |
   inserts this certificate back into the relation data.
   
   This charm is useful when developing charms or when deploying charms in non-production environment.
-
+docs: https://discourse.charmhub.io/t/self-signed-x-509-certificates-documentation/11591
 website: https://charmhub.io/self-signed-certificates
 source: https://github.com/canonical/self-signed-certificates-operator
 issues: https://github.com/canonical/self-signed-certificates-operator/issues