From a37dafb67078dbb2a64eb0d9214c867b498f73d5 Mon Sep 17 00:00:00 2001 From: Javier de la Puente Date: Fri, 29 Nov 2024 10:38:25 +0100 Subject: [PATCH] review suggestions --- charm/docs/tutorial/getting-started.md | 47 +++++++++------- .../tutorial/code/getting-started/task.yaml | 9 +++- charm/src-docs/tutorial/getting-started.md | 53 ++++++++++++------- 3 files changed, 71 insertions(+), 38 deletions(-) diff --git a/charm/docs/tutorial/getting-started.md b/charm/docs/tutorial/getting-started.md index edb0b205f..f671cab2c 100644 --- a/charm/docs/tutorial/getting-started.md +++ b/charm/docs/tutorial/getting-started.md @@ -1,6 +1,6 @@ -# 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,13 +49,11 @@ 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: @@ -62,41 +61,51 @@ NetBox requires Redis to work. You can deploy Redis with redis-k8s: 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=admin@example.com diff --git a/charm/src-docs/tutorial/code/getting-started/task.yaml b/charm/src-docs/tutorial/code/getting-started/task.yaml index 4b38be13e..c7c3f7297 100644 --- 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 index 06a00409f..115b50069 100644 --- a/charm/src-docs/tutorial/getting-started.md +++ b/charm/src-docs/tutorial/getting-started.md @@ -1,6 +1,7 @@ -# Getting Started +# Deploy the NetBox charm for the first time + ## What you’ll do - Deploy the NetBox charm. @@ -14,7 +15,7 @@ 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. @@ -22,10 +23,10 @@ your NetBox instance. 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,7 +73,7 @@ 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] @@ -80,9 +81,9 @@ Integrate redis-k8s with NetBox with: :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] @@ -90,14 +91,30 @@ NetBox requires PostgreSQL to work. Deploy and integrate with: :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]