Merge branch 'OCF-Doc51-add-helm-scripts-improvements-to-release-notes' into 'develop'

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.**

# 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:

```

./<script_to_run>.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

# 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.

## **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**

[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