review suggestions

canonical · Nov 29, 2024 · a37dafb · a37dafb
1 parent c03faad
commit a37dafb
Show file tree

Hide file tree

Showing 3 changed files with 71 additions and 38 deletions.
diff --git a/charm/docs/tutorial/getting-started.md b/charm/docs/tutorial/getting-started.md
@@ -1,6 +1,6 @@
 <!-- This tutorial should be updated in the src-docs directory. -->
 
-# Getting Started
+# Deploy the NetBox charm for the first time
 
 ## What you’ll do
 
@@ -16,27 +16,28 @@ your NetBox instance.
 
 ## Requirements
 
-- Juju 3 installed.
+- Juju 3 installed and bootstrapped to a MicroK8s controller. You can accomplish this process by using a Multipass VM as outlined in this guide: [Set up / Tear down your test environment](https://juju.is/docs/juju/set-up--tear-down-your-test-environment)
 - Juju controller that can create a model of type kubernetes.
 - Read/write access to a S3 compatible server with a bucket created.
 - Configuration compatible with the traefik-k8s charms. In the case of MicroK8S this can be achieved with the metallb addon.
 
 For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
 
-## Setting up a Tutorial Model
+## Set up a Tutorial Model
 
 To manage resources effectively and to separate this tutorial’s workload from
-your usual work, we recommend creating a new model using the following command.
+your usual work, we create a new model using the following command.
 
 ```bash
 juju add-model netbox-tutorial
 ```
 
-## Deploy the NetBox charm
+## Deploy NetBox
 
-Deploy the NetBox charm, with all its mandatory requirements (PostgreSQL, Redis and S3).
+Deploy the NetBox charm, with all its mandatory requirements (PostgreSQL, Redis and S3)
+and with the ingress.
 
-### Deploy the charms:
+### Deploy the NetBox charm
 
 ```bash
 juju deploy netbox
@@ -48,55 +49,63 @@ storage, Redis or PostgreSQL.
 Set the allowed hosts. In this example every host is allowed. For a production environment
 only the used hosts should be allowed.
 
-### Deploy the charms:
-
 ```bash
 juju config netbox django-allowed-hosts='*'
 ```
 
-### Redis
+### Deploy the Redis charm
 
 NetBox requires Redis to work. You can deploy Redis with redis-k8s:
 
 ```bash
 juju deploy redis-k8s --channel=latest/edge
 ```
 
-Integrate redis-k8s with NetBox with:
+Integrate redis-k8s with NetBox:
 
 ```bash
 juju integrate redis-k8s netbox
 ```
 
-### Deploy PostgreSQL
+### Deploy the PostgreSQL charm
 
-NetBox requires PostgreSQL to work. Deploy and integrate with:
+NetBox requires PostgreSQL to work. Deploy PostgreSQL and integrate:
 
 ```bash
 juju deploy postgresql-k8s --channel 14/stable --trust
 juju integrate postgresql-k8s netbox
 ```
 
-### Deploy s3-integrator
+### Deploy the s3-integrator charm
 
 NetBox requires an S3 integration for the uploaded files. This is because
 the NetBox charm is designed to work in a high availability (HA) configuration.
 This allows uploaded images to be placed on an S3 compatible server instead of
 the local filesystem.
 
-You can configure it with:
+Deploy the s3-integrator charm:
 
 ```bash
 juju deploy s3-integrator --channel edge
+```
+
+Configure the s3-integrator charm with your S3 information, wait for the charm to update and provide the credentials:
+
+```bash
 juju config s3-integrator endpoint="${AWS_ENDPOINT_URL}" bucket="${AWS_BUCKET}" path=/ region="${AWS_REGION}" s3-uri-style="${AWS_URI_STYLE}"
 juju wait-for application s3-integrator --query='name=="s3-integrator" && (status=="active" || status=="blocked")'
 juju run s3-integrator/leader sync-s3-credentials access-key="${AWS_ACCESS_KEY_ID}" secret-key="${AWS_SECRET_ACCESS_KEY}"
+```
+
+Once the s3-integrator charm has been deployed, integrate the charm with NetBox:
+
+```bash
 juju integrate s3-integrator netbox
 ```
 
 See the [s3-integrator charmhub page](https://charmhub.io/s3-integrator) for more information.
 
-### Deploy traefik-k8s
+### Deploy the traefik-k8s charm
 
 You need to enable MetalLb if using MicroK8s. See the [traefik-k8s charmhub page](https://charmhub.io/traefik-k8s) for more information.
 
@@ -110,7 +119,7 @@ juju integrate traefik-k8s netbox
 ```
 
 If the host `netbox_hostname` can be resolved to the correct IP (the load balancer IP),
-you should be able to browse NetBox in the url http://netbox_hostname/netbox-tutorial-netbox
+you should be able to browse NetBox in the URL http://netbox_hostname/netbox-tutorial-netbox
 
 You can check the proxied endpoints with the command:
 
@@ -119,9 +128,9 @@ juju run traefik-k8s/0 show-proxied-endpoints --format=yaml
 # [docs:traefik-show-endpoints-end]
 ```
 
-## Create superuser
+## Create a super user
 
-To be able to login to NetBox, you can create a super user with the next command:
+To be able to log in to NetBox, you can create a super user with the next command:
 
 ```bash
 juju run netbox/0 create-superuser username=admin [email protected]

diff --git a/charm/src-docs/tutorial/code/getting-started/task.yaml b/charm/src-docs/tutorial/code/getting-started/task.yaml
@@ -55,11 +55,18 @@ execute: |
   juju integrate postgresql-k8s netbox
   # [docs:juju-netbox-postgresql-end]
 
-  # [docs:juju-netbox-s3]
+  
+  # [docs:juju-deploy-s3]
   juju deploy s3-integrator --channel edge
+  # [docs:juju-deploy-s3-end]
+  
+  # [docs:juju-config-s3]
   juju config s3-integrator endpoint="${AWS_ENDPOINT_URL}" bucket="${AWS_BUCKET}" path=/ region="${AWS_REGION}" s3-uri-style="${AWS_URI_STYLE}"
   juju wait-for application s3-integrator --query='name=="s3-integrator" && (status=="active" || status=="blocked")'
   juju run s3-integrator/leader sync-s3-credentials access-key="${AWS_ACCESS_KEY_ID}" secret-key="${AWS_SECRET_ACCESS_KEY}"
+  # [docs:juju-config-s3-end]
+
+  # [docs:juju-netbox-s3]
   juju integrate s3-integrator netbox
   # [docs:juju-netbox-s3-end]
 

diff --git a/charm/src-docs/tutorial/getting-started.md b/charm/src-docs/tutorial/getting-started.md
@@ -1,6 +1,7 @@
 <!-- This tutorial should be updated in the src-docs directory. -->
 
-# Getting Started
+# Deploy the NetBox charm for the first time
+
 
 ## What you’ll do
 - Deploy the NetBox charm.
@@ -14,18 +15,18 @@ Through the process, you'll verify the workload state, and log in to
 your NetBox instance.
 
 ## Requirements
-- Juju 3 installed.
+- Juju 3 installed and bootstrapped to a MicroK8s controller. You can accomplish this process by using a Multipass VM as outlined in this guide: [Set up / Tear down your test environment](https://juju.is/docs/juju/set-up--tear-down-your-test-environment)
 - Juju controller that can create a model of type kubernetes.
 - Read/write access to a S3 compatible server with a bucket created.
 - Configuration compatible with the traefik-k8s charms. In the case of MicroK8S this can be achieved with the metallb addon.
 
 For more information about how to install Juju, see [Get started with Juju](https://juju.is/docs/olm/get-started-with-juju).
 
 
-## Setting up a Tutorial Model
+## Set up a Tutorial Model
 
 To manage resources effectively and to separate this tutorial's workload from
-your usual work, we recommend creating a new model using the following command.
+your usual work, we create a new model using the following command.
 
 ```{literalinclude} code/getting-started/task.yaml
 :language: bash
@@ -34,11 +35,12 @@ your usual work, we recommend creating a new model using the following command.
 :dedent: 2
 ```
 
-## Deploy the NetBox charm
+## Deploy NetBox
 
-Deploy the NetBox charm, with all its mandatory requirements (PostgreSQL, Redis and S3).
+Deploy the NetBox charm, with all its mandatory requirements (PostgreSQL, Redis and S3)
+and with the ingress.
 
-### Deploy the charms:
+### Deploy the NetBox charm
 
 ```{literalinclude} code/getting-started/task.yaml
 :language: bash
@@ -53,7 +55,6 @@ storage, Redis or PostgreSQL.
 Set the allowed hosts. In this example every host is allowed. For a production environment
 only the used hosts should be allowed.
 
-### Deploy the charms:
 
 ```{literalinclude} code/getting-started/task.yaml
 :language: bash
@@ -62,7 +63,7 @@ only the used hosts should be allowed.
 :dedent: 2
 ```
 
-### Redis
+### Deploy the Redis charm
 
 NetBox requires Redis to work. You can deploy Redis with redis-k8s:
 ```{literalinclude} code/getting-started/task.yaml
@@ -72,32 +73,48 @@ NetBox requires Redis to work. You can deploy Redis with redis-k8s:
 :dedent: 2
 ```
 
-Integrate redis-k8s with NetBox with:
+Integrate redis-k8s with NetBox:
 ```{literalinclude} code/getting-started/task.yaml
 :language: bash
 :start-after: [docs:juju-integrate-redis-netbox]
 :end-before: [docs:juju-integrate-redis-netbox-end]
 :dedent: 2
 ```
 
-### Deploy PostgreSQL
+### Deploy the PostgreSQL charm
 
-NetBox requires PostgreSQL to work. Deploy and integrate with:
+NetBox requires PostgreSQL to work. Deploy PostgreSQL and integrate:
 ```{literalinclude} code/getting-started/task.yaml
 :language: bash
 :start-after: [docs:juju-netbox-postgresql]
 :end-before: [docs:juju-netbox-postgresql-end]
 :dedent: 2
 ```
 
-### Deploy s3-integrator
+### Deploy the s3-integrator charm
 
 NetBox requires an S3 integration for the uploaded files. This is because
 the NetBox charm is designed to work in a high availability (HA) configuration.
 This allows uploaded images to be placed on an S3 compatible server instead of
 the local filesystem.
 
-You can configure it with:
+Deploy the s3-integrator charm:
+```{literalinclude} code/getting-started/task.yaml
+:language: bash
+:start-after: [docs:juju-deploy-s3]
+:end-before: [docs:juju-deploy-s3-end]
+:dedent: 2
+```
+
+Configure the s3-integrator charm with your S3 information, wait for the charm to update and provide the credentials:
+```{literalinclude} code/getting-started/task.yaml
+:language: bash
+:start-after: [docs:juju-config-s3]
+:end-before: [docs:juju-config-s3-end]
+:dedent: 2
+```
+
+Once the s3-integrator charm has been deployed, integrate the charm with NetBox:
 ```{literalinclude} code/getting-started/task.yaml
 :language: bash
 :start-after: [docs:juju-netbox-s3]
@@ -107,7 +124,7 @@ You can configure it with:
 
 See the [s3-integrator charmhub page](https://charmhub.io/s3-integrator) for more information.
 
-### Deploy traefik-k8s 
+### Deploy the traefik-k8s charm
 
 You need to enable MetalLb if using MicroK8s. See the [traefik-k8s charmhub page](https://charmhub.io/traefik-k8s) for more information.
 
@@ -120,7 +137,7 @@ With the next example, you can configure Traefik using path mode routing:
 ```
 
 If the host `netbox_hostname` can be resolved to the correct IP (the load balancer IP),
-you should be able to browse NetBox in the url http://netbox_hostname/netbox-tutorial-netbox
+you should be able to browse NetBox in the URL http://netbox_hostname/netbox-tutorial-netbox
 
 You can check the proxied endpoints with the command:
 ```{literalinclude} code/getting-started/task.yaml
@@ -130,8 +147,8 @@ You can check the proxied endpoints with the command:
 :dedent: 2
 ```
 
-## Create superuser
-To be able to login to NetBox, you can create a super user with the next command:
+## Create a super user
+To be able to log in to NetBox, you can create a super user with the next command:
 ```{literalinclude} code/getting-started/task.yaml
 :language: bash
 :start-after: [docs:netbox-create-superuser]