From 8cfd172ad59efb1630cb39e96076df4b932d677f Mon Sep 17 00:00:00 2001 From: Jorge Moratinos Salcines Date: Wed, 20 Aug 2025 13:30:48 +0200 Subject: [PATCH] Minor fix on release notes --- doc/gettingstarted/download.md | 42 ++++++++++ doc/gettingstarted/howtodeploy.md | 129 ++++++++++++++++++++++++++++++ doc/gettingstarted/howtorun.md | 46 +---------- doc/gettingstarted/repository.md | 0 doc/releasenotes.md | 30 +++++++ mkdocs.yml | 4 +- 6 files changed, 205 insertions(+), 46 deletions(-) create mode 100644 doc/gettingstarted/download.md create mode 100644 doc/gettingstarted/howtodeploy.md delete mode 100644 doc/gettingstarted/repository.md diff --git a/doc/gettingstarted/download.md b/doc/gettingstarted/download.md new file mode 100644 index 00000000..d94399d0 --- /dev/null +++ b/doc/gettingstarted/download.md @@ -0,0 +1,42 @@ +You can easily download CAPIF to run in local environment following next steps: + +## 1. Create a folder to download the project + +``` +mkdir OpenCAPIF + +cd OpenCAPIF +``` + +## 2. Download the deployment script + +Download the deployment / environment preparation script (press [here](https://labs.etsi.org/rep/ocf/capif/-/raw/staging/deploy.sh?inline=false) to directly download script): + + +``` +wget https://labs.etsi.org/rep/ocf/capif/-/raw/staging/deploy.sh +``` + +Make it executable: + +``` +chmod +x deploy.sh +``` + +## 3. Run the deployment script + +This script selects the branch for capif repository project to pull from. + +If you run the script without selecting a branch the the main branch is going to be selected. + +We recommend: + +* **main** branch for the most stable experience and **staging** branch for an experience with the latest features (for staging branch installation, it is strongly advisable that you may as well follow the staging documentation) + +``` +# ./deploy.sh [branch to fetch] [true or false (default) to install monitoring stack or not] + +sudo ./deploy.sh staging +``` + +> **We recommend running the deploy.sh script with root permissions! In other case, some directories may not be accessible by the project building tools and hinder the smooth installation.** diff --git a/doc/gettingstarted/howtodeploy.md b/doc/gettingstarted/howtodeploy.md new file mode 100644 index 00000000..118b26a1 --- /dev/null +++ b/doc/gettingstarted/howtodeploy.md @@ -0,0 +1,129 @@ +# How to Deploy Using Helm + +In this section we will explain how to use Helm Charts to deploy OpenCAPIF using [Helm Scripts](https://labs.etsi.org/rep/ocf/capif/-/tree/staging/helm/scripts) present at repository. + +## Overview + +Complete deployment of OpenCAPIF involves below services: + +- Hasicorp Vault. +- Montoring stack (Prometheus, Grafana, ...) +- OpenCAPIF. + +All needed files, like helm deployments and scripts are under [Helm Main] directory at OpenCAPIF repository. + +## Helm Directory + +In order to simplify the way to deploy, OCF SDG created different helms definitions to allow the deployment of all related services, like Vault, Montoring Stack and OpenCAPIF. + +Those helms are fully functional, you will need to configure each one and also load security information to vault, and also you will need the knowledge to launch helm deployment on your environment. This is ***out of the scope*** of this Documentation. + +But we also created some scripts to simplify this proccess. + +## Helm Scripts + +OCF SDG created a set of scripts to deploy/undeploy OpenCAPIF at k8s environment, and also perform some other tasks like create users, run tests suites, ... + +All scripts are stored at [Helm Scripts]. + +Just we need to keep in mind, all scripts use configurations defined under **variables.sh** and environments if them are defined. + +There are different types of scripts: + +### Deployment Management +- ***install_vault.sh***: Deploy Vault component from k8s cluster, only needed if vault is not previously deployed. If it’s deployed you can setup vault token on variables.sh. +- ***install_monitoring.sh***: Deploy monitoring on k8s cluster. +- ***install_capif.sh***: Deploy OpenCAPIF on k8s cluster. It will be deployed on configured namespace with domain and hostnames configured under variables.sh. +- ***uninstall_vault.sh***: Rollback Vault component from k8s cluster. +- ***uninstall_monitoring.sh***: Rollback monitoring components from k8s cluster. +- ***uninstall_capif.sh***: Rollback OpenCAPIF from k8s cluster. + +### Manage remote users +- ***create_remote_users.sh***: This script create users setup by parameters on deployed OpenCAPIF. Those users are created by administrator. +- ***remove_remote_users.sh***: This script removes user from deployed OpenCAPIF. +- ***remove_remote_users_by_prefix.sh***:: This script removes users by prefix. + +### Obtain DNS resolution +- ***get_ingress.sh***: This create a configuration for dns fixed resolution for ingress configured in namespace passed by parameters. +- ***set_ingress.sh***: This scripts adds to /etc/hosts the fixed DNS resolution for ingress setup for namespace passed by parameters. + +### Run Robot Tests Suites +- ***run_remote_capif_tests.sh***: This scripts launch Robot Test docker image on current machine to reach deployed OpenCAPIF. Is useful to launch with “--include smoke” in order to ensure all is deployed properly. + +### Create Testing Dummy Info +- ***populate_create_remote_dummy_users.sh***: : Create Dummy providers and invokers, publish service APIs and creates security context for invokers. +- ***populate_remove_remote_dummy_users.sh***: Remove dummy information created. + +### How to Run Scripts + +#### Configure environment parameters + +***variables.sh*** contains all configuration that will be used on remote operation. + +Currently also environment files are supported. Those environment files contains the override of variables present on variables.sh. + +If you want to use environment files, just place a file under /helm/scripts/envs with name of your environment and extension ".env". You can see the example environment [here](https://labs.etsi.org/rep/ocf/capif/-/tree/staging/helm/scripts/envs/example.env) + +After add this environment file, you just need to indicate when you run any of the scripts at /helm/scripts directory, in this way: + +``` +./.sh [environment] [command_options] +``` + +#### **Example** + +Create a file under ***/helm/scripts/envs*** called **production.env** with below information: + +``` +# Setup kubeconfig to be used +export CUSTOM_KUBECONFIG="production.kubeconfig" + +# Setup Vault parameters to deploy on this environment +export VAULT_HOSTNAME=vault.company.production +export DOMAIN1=*.company.production +export DOMAIN2=*.company.staging +export DOMAIN3=*.company.dev + +# Setup Monitoring parameters +export PROMETHEUS_HOSTNAME=prometheus.company.production + +# Setup OpenCAPIF parameters +export CAPIF_HOSTNAME="capif.company.production" +export REGISTER_HOSTNAME="register.company.production" +export CAPIF_NAMESPACE=ocf-capif +export CAPIF_CI_ENV_ENDPOINT=latest +export CAPIF_DOMAIN=company.production +export CAPIF_IMAGE_TAG="v3.0.0-release" +``` + +This is our environment file, with specific information of our environment. Now we can run for example the deployment scripts, just adding as first parameter the name of environment (name of file without extension): + +``` +./install_vault.sh production +./install_monitoring.sh production +./install_capif.sh production +``` + +After deploy OpenCAPIF we can run tests for example: + +``` +./run_remote_capif_tests.sh production --include capif_api_invoker_management-1 +``` + +Or run any other task related, for example, creation of users at new environment: + +``` +./create_remote_users.sh production -u user -p pass +``` + + +> **NOTE: You can check also information of how to use the scripts by including "-h" flag (not present on Deployment Management scripts)** + + + + +[Test Plan Directory]: .././testing/testplan/README.md "Test Plan" +[Testing with Robot Framework]: .././testing/robotframework/README.md "Robot Framework" +[Testing with Postman]: .././testing/postman/README.md "Postman" +[Helm Main]: https://labs.etsi.org/rep/ocf/capif/-/tree/staging/helm/ "Helm main directory" +[Helm Scripts]: https://labs.etsi.org/rep/ocf/capif/-/tree/staging/helm/scripts "Helm scripts" \ No newline at end of file diff --git a/doc/gettingstarted/howtorun.md b/doc/gettingstarted/howtorun.md index a42da808..0703ca98 100644 --- a/doc/gettingstarted/howtorun.md +++ b/doc/gettingstarted/howtorun.md @@ -1,51 +1,7 @@ -# How to Run +# How to Run Locally > Capif services are developed under [services folder](https://labs.etsi.org/rep/ocf/capif/-/tree/main/services). -### Downloading the project - -You can easily download CAPIF to run in local environment following next steps: - -#### 1. Create a folder to download the project - -``` -mkdir OpenCAPIF - -cd OpenCAPIF -``` - -#### 2. Download the deployment script - -Download the deployment / environment preparation script (press [here](https://labs.etsi.org/rep/ocf/capif/-/raw/staging/deploy.sh?inline=false) to directly download script): - - -``` -wget https://labs.etsi.org/rep/ocf/capif/-/raw/staging/deploy.sh -``` - -Make it executable: - -``` -chmod +x deploy.sh -``` - -#### 3. Run the deployment script - -This script selects the branch for capif repository project to pull from. - -If you run the script without selecting a branch the the main branch is going to be selected. - -We recommend: - -* **main** branch for the most stable experience and **staging** branch for an experience with the latest features (for staging branch installation, it is strongly advisable that you may as well follow the staging documentation) - -``` -# ./deploy.sh [branch to fetch] [true or false (default) to install monitoring stack or not] - -sudo ./deploy.sh staging -``` - -> **We recommend running the deploy.sh script with root permissions! In other case, some directories may not be accessible by the project building tools and hinder the smooth installation.** ### Run All CAPIF Services locally with Docker images To run using docker and docker compose, version 2.10 or higher, you must ensure you have those tools installed in your machine. Also to simplify the process, we have 3 scripts allowing docker images to deploy, check and cleanup. diff --git a/doc/gettingstarted/repository.md b/doc/gettingstarted/repository.md deleted file mode 100644 index e69de29b..00000000 diff --git a/doc/releasenotes.md b/doc/releasenotes.md index 98a1714c..1a6e4483 100644 --- a/doc/releasenotes.md +++ b/doc/releasenotes.md @@ -1,3 +1,29 @@ +## **Release X.0.0** + +### **Technical Debt Solved** + +#### **Improved helm and tools scripts** + +Helm scripts under helm/scripts directory are improved with next features: + +- **install_capif.sh** Now supports deployment of release 3.0.0, including celery charts configuration. +- All helm scripts now supports addition of environment files to simplify the way to overwrite values in variables according to each environment. Check [How to Deploy Using Helm] Section to learn how to use this functionality. +- **variables.sh** include more variables: + - **BASE_DOCKER_REGISTRY**: domain to use when image will be retrieved to deploy services. + - **LOG_LEVEL**: Now you can stablish the log level at all services on deployment, setting it to [CRITICAL, FATAL, ERROR, WARNING, WARN, INFO, DEBUG, NOTSET]. + - **REGISTER_ADMIN_USER** and **REGISTER_ADMIN_PASSWORD**: Setup admin username and password to run scripts like create_remote_users.sh, run_remote_capif_tests.sh, ... + - **SKOONER_HOSTNAME**: Setup Skooner hostname. + - **GRAFANA_HOSTNAME**: Setup Grafana hostname. + - **MONITORING_GRAFANA_ENABLED**: Setup if grafana is enabled or not at monitoring deployment. + - **MONITORING_PROMETHEUS_ENABLED**: Setup if prometheus is enabled or not at monitoring deployment. +- **push_base_images_ocf.sh** includes now the busybox image used by mongo chart. + +### **Documentation** + +- New section [How to Deploy Using Helm] created. This section includes a guide of how to use helm scripts to deploy all components (including OpenCAPIF) on a k8s environment. +- Change "How to Run" section name to [How to Run locally]. +- New section called [Download Repository] included in documentation. + ## **Release 3.0.0** ### **New Features** @@ -429,3 +455,7 @@ This Release also includes a Robot Test Suite for all those services and a Postm [New Registration Demo]: https://www.youtube.com/watch?v=sn-tN6eRvv8 "New Registration Demo" [CICD Wiki]: https://labs.etsi.org/rep/ocf/community/-/wikis/OCF-CICD "CI/CD Wiki" [Upgrade Release 17 to 18 Wiki]: https://labs.etsi.org/rep/ocf/community/-/wikis/3GPP-Release-18-upgrade "Upgrade Release 17 to 18 Wiki" + +[How to Deploy Using Helm]: ./gettingstarted/howtodeploy.md "How to Deploy Using Helm" +[Download Repository]: ./gettingstarted/download.md "Download Repository" +[How to Run Locally]: ./gettingstarted/howtorun.md "How to Run Locally" \ No newline at end of file diff --git a/mkdocs.yml b/mkdocs.yml index d428168f..22ebe4a2 100644 --- a/mkdocs.yml +++ b/mkdocs.yml @@ -88,7 +88,9 @@ nav: - Introduction: ./helper/helper.md - Swagger: ./helper/swagger.md - Getting Started: - - How to Run: ./gettingstarted/howtorun.md + - Download Repository: ./gettingstarted/download.md + - How to Run Locally: ./gettingstarted/howtorun.md + - How to Deploy Using Helm: ./gettingstarted/howtodeploy.md - Features: - Vendor Extensibility: ./vendor-ext/vendor-ext.md - Api Status: ./api-status/api-status.md -- GitLab