diff --git a/doc/gettingstarted/download.md b/doc/gettingstarted/download.md new file mode 100644 index 0000000000000000000000000000000000000000..d94399d04fef453e4749b337240b2983391831c6 --- /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 0000000000000000000000000000000000000000..118b26a13d6781877dcb6e25bf07c09719009eb6 --- /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 a42da808a59cc2661421593e65f6164fd27e25dd..0703ca9884c4057a65884676256b6475ab91fbcd 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 e69de29bb2d1d6434b8b29ae775ad8c2e48c5391..0000000000000000000000000000000000000000 diff --git a/doc/releasenotes.md b/doc/releasenotes.md index 98a1714c4c2c11aa1b325881f77e13840c66d76f..1a6e448348d7f55171d25722464b9e7b61e51c64 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 d428168fffc68983f30947b9f056930935b2cbbd..22ebe4a2d703cdacf676defa2e3b67c40e04257f 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