diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index dfcf98b..98b19c1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -2,53 +2,13 @@ ## Prerequisites -To make contributions to this repository, the following software and tools needs to be installed in your development environment. +To make contributions to this repository, the following software is needed to be installed in your development environment. Please [set up your environment][set-up-environment] before development. - A Kubernetes cluster - Juju 3.x - Juju controller bootstrapped onto the K8s cluster - Terraform -## Prepare Development Environment - -Install Microk8s: - -```console -sudo snap install microk8s --channel=1.27-strict/stable -sudo usermod -a -G snap_microk8s $USER -newgrp snap_microk8s -``` - -Enable `storage` plugin for Microk8s: - -```console -sudo microk8s enable hostpath-storage -``` - -Install Juju: - -```console -sudo snap install juju --channel=3.1/stable -``` - -Install Terraform: - -```console -sudo snap install --classic terraform -``` - -Bootstrap the Juju Controller using Microk8s: - -```console -juju bootstrap microk8s -``` - -Add a Juju model: - -```console -juju add-model -```` - ## Development and Testing The Terraform module uses the Juju provider to provision Juju resources. Please refer to the [Juju provider documentation](https://registry.terraform.io/providers/juju/juju/latest/docs) for more information. @@ -61,13 +21,13 @@ Initialise the provider: terraform init ``` -Formats the *.tf files to a canonical format and style: +Format the *.tf files to a canonical format and style: ```console terraform fmt ``` -Check the syntactical validation: +Check the syntax: ```console terraform validate @@ -77,4 +37,6 @@ Preview the changes: ```console terraform plan -``` \ No newline at end of file +``` + +[set-up-environment]: [https://discourse.charmhub.io/t/set-up-your-development-environment-with-microk8s-for-juju-terraform-provider/13109] diff --git a/README.md b/README.md index 8fd68e3..2fdd940 100644 --- a/README.md +++ b/README.md @@ -1,23 +1,28 @@ # SD-Core Terraform Module -This folder contains the [Terraform][Terraform] module for [sdcore-k8s][sdcore-k8s] consisting of [sdcore-control-plane-k8s][sdcore-control-plane-k8s] and [sdcore-user-plane-k8s][sdcore-user-plane-k8s] modules. +This project contains 3 [Terraform][Terraform] modules to deploy the following SD-Core bundles: [SD-Core][sdcore-k8s], [SD-Core CP][sdcore-control-plane-k8s] and [SD-Core UP][sdcore-user-plane-k8s]. -The modules use the [Terraform Juju provider][Terraform Juju provider] to model the charm deployment onto any Kubernetes environment managed by [Juju][Juju]. +The modules use the [Terraform Juju provider][Terraform Juju provider] to model the bundle deployment onto any Kubernetes environment managed by [Juju][Juju]. + +`sdcore-k8s` module deploys a standalone 5G core network. This module contains the 5G control plane functions, the UPF, Webui, Grafana Agent, Traefik, Self Signed Certificates and MongoDB. + +`sdcore-control-plane-k8s` module deploys the 5G control plane and the `sdcore-user-plane-k8s` module deploys only the 5G user plane. Hence, the SD-Core 5G core network deployment is ensured following the Control and User Plane Separation (CUPS) principles. ## Module structure - **main.tf** - Defines the Juju application to be deployed. -- **variables.tf** - Allows customization of the deployment. Except for exposing the deployment options (Juju model name, channel) also allows overwriting charm's default configuration. +- **variables.tf** - Allows customization of the deployment including Juju model name, charm's channel and configuration. - **terraform.tf** - Defines the Terraform provider. ## Deploying sdcore-k8s module ### Pre-requisites -The following tools needs to be installed and should be running in the environment. +The following tools need to be installed and should be running in the environment. - A Kubernetes host with a CPU supporting AVX2 and RDRAND instructions (Intel Haswell, AMD Excavator or equivalent) - A Kubernetes cluster with the `Multus` and `Metallb` addon enabled. +- The Load balancer (MetalLB) has address range with at least 3 available IP addresses - Juju 3.x - Juju controller bootstrapped onto the K8s cluster - Terraform @@ -39,6 +44,7 @@ sudo microk8s addons repo add community https://github.com/canonical/microk8s-co ``` Enable the `hostpath-storage`, `multus` and `metallb` MicroK8s addons. + ```shell sudo microk8s enable hostpath-storage sudo microk8s enable multus @@ -68,7 +74,6 @@ terraform init Create the `terraform.tfvars` file to specify the name of the Juju model to deploy to. Reusing already existing model is not recommended. ```yaml -# Mandatory Config Options model_name = "put your model-name here" # Customize the configuration variables here if needed diff --git a/main.tf b/main.tf index 7f663b6..29632f7 100644 --- a/main.tf +++ b/main.tf @@ -1,9 +1,6 @@ # Copyright 2024 Canonical Ltd. # See LICENSE file for licensing details. -# Copyright 2024 Canonical Ltd. -# See LICENSE file for licensing details. - resource "juju_model" "sdcore" { name = var.model_name } @@ -12,7 +9,7 @@ module "amf" { source = "git::https://github.com/canonical/sdcore-amf-k8s-operator//terraform" model_name = juju_model.sdcore.name channel = var.channel - amf-config = var.amf_config + config = var.amf_config } module "ausf" { @@ -37,7 +34,7 @@ module "nssf" { source = "git::https://github.com/canonical/sdcore-nssf-k8s-operator//terraform" model_name = juju_model.sdcore.name channel = var.channel - nssf-config = var.nssf_config + config = var.nssf_config } module "pcf" { @@ -74,35 +71,35 @@ module "mongodb" { source = "./modules/mongodb-k8s" model_name = juju_model.sdcore.name channel = var.mongo_channel - mongo-config = var.mongo_config + config = var.mongo_config } module "grafana-agent" { source = "./modules/grafana-agent-k8s" model_name = juju_model.sdcore.name channel = var.grafana_agent_channel - grafana-config = var.grafana_agent_config + config = var.grafana_agent_config } module "self-signed-certificates" { source = "git::https://github.com/canonical/self-signed-certificates-operator.git//terraform" model_name = juju_model.sdcore.name channel = var.self_signed_certificates_channel - cert-config = var.self_signed_certificates_config + config = var.self_signed_certificates_config } module "traefik" { source = "./modules/traefik-k8s" model_name = juju_model.sdcore.name channel = var.traefik_channel - traefik-config = var.traefik_config + config = var.traefik_config } module "upf" { source = "git::https://github.com/canonical/sdcore-upf-k8s-operator//terraform" model_name = juju_model.sdcore.name channel = var.channel - amf-config = var.upf_config + config = var.upf_config } # Integrations for `fiveg-nrf` endpoint diff --git a/modules/grafana-agent-k8s/README.md b/modules/grafana-agent-k8s/README.md index 1afe77a..ac13893 100644 --- a/modules/grafana-agent-k8s/README.md +++ b/modules/grafana-agent-k8s/README.md @@ -9,8 +9,8 @@ The base module is not intended to be deployed in separation (it is possible tho ## Module structure - **main.tf** - Defines the Juju application to be deployed. -- **variables.tf** - Allows customization of the deployment. Except for exposing the deployment options (Juju model name, channel or application name) also models the charm configuration. -- **output.tf** - Responsible for integrating the module with other Terraform modules, primarily by defining potential integration endpoints (charm integrations), but also by exposing the application name. +- **variables.tf** - Allows customization of the deployment such as Juju model name, application name, charm's channel and configuration. +- **output.tf** - Responsible for integrating the module with other Terraform modules, primarily by defining potential integration endpoints (charm integrations) together with exposing the application name. - **terraform.tf** - Defines the Terraform provider. ## Pre-requisites @@ -60,4 +60,3 @@ The complete list of available integrations can be found [here][grafana-agent-in [Juju]: https://juju.is [grafana-agent-integrations]: https://charmhub.io/grafana-agent-k8s/integrations [set-up-environment]: [https://discourse.charmhub.io/t/set-up-your-development-environment-with-microk8s-for-juju-terraform-provider/13109] - diff --git a/modules/mongodb-k8s/README.md b/modules/mongodb-k8s/README.md index 7a55107..42942e6 100644 --- a/modules/mongodb-k8s/README.md +++ b/modules/mongodb-k8s/README.md @@ -9,8 +9,8 @@ The base module is not intended to be deployed in separation (it is possible tho ## Module structure - **main.tf** - Defines the Juju application to be deployed. -- **variables.tf** - Allows customization of the deployment such as Juju model name, channel or application name and charm configuration. -- **output.tf** - Responsible for integrating the module with other Terraform modules, primarily by defining potential integration endpoints (charm integrations), but also by exposing the application name. +- **variables.tf** - Allows customization of the deployment such as Juju model name, application name, charm's channel and configuration. +- **output.tf** - Responsible for integrating the module with other Terraform modules, primarily by defining potential integration endpoints (charm integrations) together with exposing the application name. - **terraform.tf** - Defines the Terraform provider. ## Using mongodb-k8s base module in higher level modules diff --git a/modules/mongodb-k8s/variables.tf b/modules/mongodb-k8s/variables.tf index 7a6b2c8..f42e9e8 100644 --- a/modules/mongodb-k8s/variables.tf +++ b/modules/mongodb-k8s/variables.tf @@ -20,7 +20,7 @@ variable "channel" { } variable "config" { - description = "Additional configuration for the MongoDB. Details about available options can be found at https://charmhub.io/mongodb-k8s/configure?channel=6/edge." + description = "Additional configuration for the MongoDB. Details about available options can be found at https://charmhub.io/mongodb-k8s/configure?channel=6/beta." type = map(string) default = {} } \ No newline at end of file diff --git a/modules/sdcore-control-plane-k8s/README.md b/modules/sdcore-control-plane-k8s/README.md index ad14b42..469284a 100644 --- a/modules/sdcore-control-plane-k8s/README.md +++ b/modules/sdcore-control-plane-k8s/README.md @@ -1,24 +1,25 @@ # SD-Core Control Plane Terraform Module -This folder contains the [Terraform][Terraform] module for the [sdcore-control-plane-k8s][sdcore-control-plane-k8s] bundle. +This folder contains the [Terraform][Terraform] module to deploy the [sdcore-control-plane-k8s][sdcore-control-plane-k8s] bundle. The module uses the [Terraform Juju provider][Terraform Juju provider] to model the charm deployment onto any Kubernetes environment managed by [Juju][Juju]. -The module can be used to deploy the `sdcore-control-plane-k8s` separately as well as a part of `sdcore-k8s` module, depending on the deployment architecture. +The module can be used to deploy the `sdcore-control-plane-k8s` separately as well as a part of the higher level modules depending on the deployment architecture. ## Module structure - **main.tf** - Defines the Juju application to be deployed. -- **variables.tf** - Allows customization of the deployment. Except for exposing the deployment options (Juju model name, channel) also allows overwriting charm's default configuration. +- **variables.tf** - Allows customization of the deployment including Juju model name, charm's channel and configuration. - **terraform.tf** - Defines the Terraform provider. ## Deploying sdcore-control-plane-k8s module separately ### Pre-requisites -The following tools needs to be installed and should be running in the environment. +The following tools need to be installed and should be running in the environment. -- A Kubernetes cluster with the `Multus` and `Metallb` addon enabled. +- A Kubernetes cluster with the `Multus` and `Metallb` addon enabled +- The Load balancer (MetalLB) has address range with at least 2 available IP addresses - Juju 3.x - Juju controller bootstrapped onto the K8s cluster - Terraform @@ -40,6 +41,7 @@ sudo microk8s addons repo add community https://github.com/canonical/microk8s-co ``` Enable the `hostpath-storage`, `multus` and `metallb` MicroK8s addons. + ```shell sudo microk8s enable hostpath-storage sudo microk8s enable multus @@ -69,7 +71,6 @@ terraform init Create the `terraform.tfvars` file to specify the name of the Juju model to deploy to. Reusing already existing model is not recommended. ```yaml -# Mandatory Config Options model_name = "put your model-name here" # Customize the configuration variables here if needed diff --git a/modules/sdcore-control-plane-k8s/main.tf b/modules/sdcore-control-plane-k8s/main.tf index f0eeea9..0033372 100644 --- a/modules/sdcore-control-plane-k8s/main.tf +++ b/modules/sdcore-control-plane-k8s/main.tf @@ -9,7 +9,7 @@ module "amf" { source = "git::https://github.com/canonical/sdcore-amf-k8s-operator//terraform" model_name = juju_model.sdcore.name channel = var.channel - amf-config = var.amf_config + config = var.amf_config } module "ausf" { @@ -31,10 +31,10 @@ module "nrf" { } module "nssf" { - source = "git::https://github.com/canonical/sdcore-nssf-k8s-operator//terraform" - model_name = juju_model.sdcore.name - channel = var.channel - nssf-config = var.nssf_config + source = "git::https://github.com/canonical/sdcore-nssf-k8s-operator//terraform" + model_name = juju_model.sdcore.name + channel = var.channel + config = var.nssf_config } module "pcf" { @@ -68,31 +68,31 @@ module "webui" { } module "mongodb" { - source = "./modules/mongodb-k8s" - model_name = juju_model.sdcore.name - channel = var.mongo_channel - mongo-config = var.mongo_config + source = "./modules/mongodb-k8s" + model_name = juju_model.sdcore.name + channel = var.mongo_channel + config = var.mongo_config } module "grafana-agent" { - source = "./modules/grafana-agent-k8s" - model_name = juju_model.sdcore.name - channel = var.grafana_agent_channel - grafana-config = var.grafana_agent_config + source = "./modules/grafana-agent-k8s" + model_name = juju_model.sdcore.name + channel = var.grafana_agent_channel + config = var.grafana_agent_config } module "self-signed-certificates" { - source = "git::https://github.com/canonical/self-signed-certificates-operator.git//terraform" - model_name = juju_model.sdcore.name - channel = var.self_signed_certificates_channel - cert-config = var.self_signed_certificates_config + source = "git::https://github.com/canonical/self-signed-certificates-operator.git//terraform" + model_name = juju_model.sdcore.name + channel = var.self_signed_certificates_channel + config = var.self_signed_certificates_config } module "traefik" { - source = "./modules/traefik-k8s" - model_name = juju_model.sdcore.name - channel = var.traefik_channel - traefik-config = var.traefik_config + source = "./modules/traefik-k8s" + model_name = juju_model.sdcore.name + channel = var.traefik_channel + config = var.traefik_config } # Integrations for `fiveg-nrf` endpoint diff --git a/modules/sdcore-control-plane-k8s/variables.tf b/modules/sdcore-control-plane-k8s/variables.tf index 6ecf9de..fc7903b 100644 --- a/modules/sdcore-control-plane-k8s/variables.tf +++ b/modules/sdcore-control-plane-k8s/variables.tf @@ -50,7 +50,7 @@ variable "nssf_config" { } variable "mongo_config" { - description = "Application config for the NSSF. Details about available options can be found at https://charmhub.io/sdcore-nssf-k8s-operator/configure." + description = "Additional configuration for the MongoDB. Details about available options can be found at https://charmhub.io/mongodb-k8s/configure?channel=6/beta." type = map(string) default = {} } diff --git a/modules/sdcore-user-plane-k8s/README.md b/modules/sdcore-user-plane-k8s/README.md index 8d65c0a..7d29d18 100644 --- a/modules/sdcore-user-plane-k8s/README.md +++ b/modules/sdcore-user-plane-k8s/README.md @@ -1,25 +1,26 @@ # SD-Core Control Plane Terraform Module -This folder contains the [Terraform][Terraform] module for the [sdcore-user-plane-k8s][sdcore-user-plane-k8s] bundle. +This folder contains the [Terraform][Terraform] module to deploy the [sdcore-user-plane-k8s][sdcore-user-plane-k8s] bundle. The module uses the [Terraform Juju provider][Terraform Juju provider] to model the charm deployment onto any Kubernetes environment managed by [Juju][Juju]. -The module can be used to deploy the `sdcore-user-plane-k8s` separately as well as a part of `sdcore-k8s` module, depending on the deployment architecture. +The module can be used to deploy the `sdcore-user-plane-k8s` separately as well as a part of the higher level modules, depending on the deployment architecture. ## Module structure - **main.tf** - Defines the Juju application to be deployed. -- **variables.tf** - Allows customization of the deployment. Except for exposing the deployment options (Juju model name, channel) also allows overwriting charm's default configuration. +- **variables.tf** - Allows customization of the deployment including Juju model name, charm's channel and configuration. - **terraform.tf** - Defines the Terraform provider. ## Deploying sdcore-user-plane-k8s module separately ### Pre-requisites -The following tools needs to be installed and should be running in the environment. +The following tools need to be installed and should be running in the environment. - A Kubernetes host with a CPU supporting AVX2 and RDRAND instructions (Intel Haswell, AMD Excavator or equivalent) - A Kubernetes cluster with the `Multus` and `Metallb` addon enabled. +- The Load balancer (MetalLB) has address range with at least 1 available IP address - Juju 3.x - Juju controller bootstrapped onto the K8s cluster - Terraform @@ -41,6 +42,7 @@ sudo microk8s addons repo add community https://github.com/canonical/microk8s-co ``` Enable the `hostpath-storage`, `multus` and `metallb` MicroK8s addons. + ```shell sudo microk8s enable hostpath-storage sudo microk8s enable multus @@ -70,7 +72,6 @@ terraform init Create the `terraform.tfvars` file to specify the name of the Juju model to deploy to. Reusing already existing model is not recommended. ```yaml -# Mandatory Config Options model_name = "put your model-name here" # Customize the configuration variables here if needed diff --git a/modules/sdcore-user-plane-k8s/main.tf b/modules/sdcore-user-plane-k8s/main.tf index 1a2e557..aacb326 100644 --- a/modules/sdcore-user-plane-k8s/main.tf +++ b/modules/sdcore-user-plane-k8s/main.tf @@ -9,14 +9,14 @@ module "upf" { source = "git::https://github.com/canonical/sdcore-upf-k8s-operator//terraform" model_name = juju_model.sdcore.name channel = var.channel - amf-config = var.upf_config + config = var.upf_config } module "grafana-agent" { source = "./modules/grafana-agent-k8s" model_name = juju_model.sdcore.name channel = var.grafana_agent_channel - grafana-config = var.grafana_agent_config + config = var.grafana_agent_config } # Integrations for `metrics` endpoint diff --git a/modules/traefik-k8s/README.md b/modules/traefik-k8s/README.md index b22fc44..2f1ac27 100644 --- a/modules/traefik-k8s/README.md +++ b/modules/traefik-k8s/README.md @@ -9,8 +9,8 @@ The base module is not intended to be deployed in separation (it is possible tho ## Module structure - **main.tf** - Defines the Juju application to be deployed. -- **variables.tf** - Allows customization of the deployment. Except for exposing the deployment options (Juju model name, channel or application name) also models the charm configuration. -- **output.tf** - Responsible for integrating the module with other Terraform modules, primarily by defining potential integration endpoints (charm integrations), but also by exposing the application name. +- **variables.tf** - Allows customization of the deployment such as Juju model name, application name, charm's channel and configuration. +- **output.tf** - Responsible for integrating the module with other Terraform modules, primarily by defining potential integration endpoints (charm integrations) together with exposing the application name. - **terraform.tf** - Defines the Terraform provider. ## Pre-requisites diff --git a/variables.tf b/variables.tf index e9e9324..0c9e104 100644 --- a/variables.tf +++ b/variables.tf @@ -62,7 +62,7 @@ variable "nssf_config" { } variable "mongo_config" { - description = "Application config for the NSSF. Details about available options can be found at https://charmhub.io/sdcore-nssf-k8s-operator/configure." + description = "Additional configuration for the MongoDB. Details about available options can be found at https://charmhub.io/mongodb-k8s/configure?channel=6/beta." type = map(string) default = {} }