From 0c6c23f8d6cda3ba497ca7df81f9258a54c3258f Mon Sep 17 00:00:00 2001 From: gatici Date: Thu, 17 Aug 2023 02:04:25 +0300 Subject: [PATCH] Add documentation to Charmhub Signed-off-by: gatici --- README.md | 61 +++++++++++++++++++--- docs/explanation/e-configure.md | 47 +++++++++++++++++ docs/explanation/e-interfaces.md | 28 ++++++++++ docs/how-to/h-manage-app.md | 16 ++++++ docs/how-to/h-manage-units.md | 23 ++++++++ docs/index.md | 47 +++++++++++++++++ docs/reference/.gitkeep | 0 docs/tutorial/t-deploy.md | 32 ++++++++++++ docs/tutorial/t-get-signed-certificates.md | 25 +++++++++ docs/tutorial/t-overview.md | 24 +++++++++ docs/tutorial/t-setup-environment.md | 45 ++++++++++++++++ metadata.yaml | 2 +- 12 files changed, 342 insertions(+), 8 deletions(-) create mode 100644 docs/explanation/e-configure.md create mode 100644 docs/explanation/e-interfaces.md create mode 100644 docs/how-to/h-manage-app.md create mode 100644 docs/how-to/h-manage-units.md create mode 100644 docs/index.md create mode 100644 docs/reference/.gitkeep create mode 100644 docs/tutorial/t-deploy.md create mode 100644 docs/tutorial/t-get-signed-certificates.md create mode 100644 docs/tutorial/t-overview.md create mode 100644 docs/tutorial/t-setup-environment.md diff --git a/README.md b/README.md index 33e9476..0e49829 100644 --- 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 -juju relate self-signed-certificates +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 +``` + +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 +``` diff --git a/docs/explanation/e-configure.md b/docs/explanation/e-configure.md new file mode 100644 index 0000000..235b850 --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/explanation/e-interfaces.md b/docs/explanation/e-interfaces.md new file mode 100644 index 0000000..a921b59 --- /dev/null +++ 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 +``` + +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 +``` \ No newline at end of file diff --git a/docs/how-to/h-manage-app.md b/docs/how-to/h-manage-app.md new file mode 100644 index 0000000..58b7599 --- /dev/null +++ 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 +``` \ No newline at end of file diff --git a/docs/how-to/h-manage-units.md b/docs/how-to/h-manage-units.md new file mode 100644 index 0000000..30ddb00 --- /dev/null +++ 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 +``` + +Note: The operator does not support multiple replicas at the moment. +Warning: scaling-down to zero units will destroy your data! \ No newline at end of file diff --git a/docs/index.md b/docs/index.md new file mode 100644 index 0000000..ea82cad --- /dev/null +++ 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)
Get started - a hands-on introduction to using Self Signed X.509 Certificates for new users
| [How-to guides](/t/self-signed-x-509-certificates-how-to-manage-units/11594?channel=edge)
Step-by-step guides covering key operations and common tasks | +| [Reference](https://charmhub.io/self-signed-certificates/actions?channel=edge)
Technical information - specifications, APIs, architecture | [Explanation](/t/self-signed-x-509-certificates-explanations-interface-endpoints/11593?channel=edge)
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] \ No newline at end of file diff --git a/docs/reference/.gitkeep b/docs/reference/.gitkeep new file mode 100644 index 0000000..e69de29 diff --git a/docs/tutorial/t-deploy.md b/docs/tutorial/t-deploy.md new file mode 100644 index 0000000..130f0ad --- /dev/null +++ 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). \ No newline at end of file diff --git a/docs/tutorial/t-get-signed-certificates.md b/docs/tutorial/t-get-signed-certificates.md new file mode 100644 index 0000000..3df9dc5 --- /dev/null +++ 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/ 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 +``` \ No newline at end of file diff --git a/docs/tutorial/t-overview.md b/docs/tutorial/t-overview.md new file mode 100644 index 0000000..b2e3ac0 --- /dev/null +++ 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 new file mode 100644 index 0000000..c873705 --- /dev/null +++ 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. +``` \ No newline at end of file diff --git a/metadata.yaml b/metadata.yaml index c49c762..368454e 100644 --- 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