Once the components are developed and their images are published in some accesible registry, the next step is to integrate them into the Caas Framework. The integration of a new component into the Caas Framework is done by adding the component manifests files to the repository and extending the Kustomization file to include those manifests files in the deployment.
This document contains the guidelines for integrating a new component into the Caas Framework. The final target in the integration of a new component into the Caas Framework is to submit a merge request. The merge request will be reviewed by the project maintainers and if it is accepted it will be merged into the main branch.
The merge request should contain the following information:
- A folder with the component manifests files.
- The required sections in the Kustomization file to include those manifests in the Caas Framework deployment.
In the following sections we will explain how to create the merge request with the required information.
## Table of contents
## Merge request initialisation
There are many ways to create a merge request in Gitlab. In this section we will explain some of them.
- From an issue, which is the recommended way.
- From a branch.
### From an issue
This is the recommended way to create a merge request. The issue should be created before starting the integration of a new component into the Caas Framework.
-[Create a new issue](../../../-/issues/new)
You can additionally link the issue with the [requirement](https://git.code.tecnalia.com/emerald/private/requirements/-/issues) that this issue contributes to fulfil.
Once the issue is created, you can create a merge request from the issue. The merge request will be linked to the issue and the issue will be automatically closed when the merge request is accepted.
The creation of the merge request from the issue is done by clicking on the **Create merge request** button in the issue page. That will also include the creation of a new branch in the repository to hold the changes necessary to integrate the component.
The merge request will be annotated as **draft** so that you can work without the intervention of the project maintainers. Once the component is ready for review, you can change the status of the merge request to **ready for review**.
### From a branch before adding the component
This is an alternative way to create a merge request. You can create a new branch in the repository and then create a merge request from that branch. In this case, it is recommended to create the merge request as a **draft** so that you can work without the intervention of the project maintainers. Once the component is ready for review, you can change the status of the merge request to **ready for review**.
### From a branch after adding the component
Another way to work is to clone the repository, add the component to the repository, and then create a merge request from the branch where you added the component.
The first step to integrate a new component into the Caas Framework is to create a folder in the repository to hold the component manifests files. The folder should be created in the root of the repository and should have the name of the component. The folder will contain the manifests files of the component.
i.e. for the amoe component, the folder should be named `amoe` and should contain the manifests files of the component.
```bash
mkdir amoe
```
The type of the manifests files can be different depending on the component. The most common types are:
- jobs
- services
- deployments
- ingresses
### Add the component manifests files
The next step is to add the component manifests files to the folder created in the previous step. We recommend to prepend the name of the file with a number to indicate the order in which the files should be applied. There are example of names into the `rcm` component.
### ConfigMaps
It is recommended to create Configmaps using the `kustomize` tool. The contents of the ConfigMaps for the component should be stored in a folder `configmaps` in the component folder.
### Secrets
The Secrets will be created using the `kustomize` tool. The files to be used for the secrets generation should be **NOT** be stored in the repository. Therefore, the files with the secrets should be added as excluded files in the `.gitignore` file.
## Extend the Kustomization file
The next step is to extend the Kustomization file to include the manifests files of the component. The Kustomization file is located in the root of the repository and is named `kustomization.yaml`. The Kustomization file is a YAML file that contains the list of the manifests files that should be included in the deployment.
To extend the Kustomization file it is recommended to use the `kustomize` tool. The `kustomize` tool is a CLI tool that allows you to manage the Kustomization file. To install the `kustomize` tool you can follow the instructions in the [official documentation](https://kubectl.docs.kubernetes.io/installation/kustomize/).
The relevant sections in the Kustomization file are:
-`resources`: This section contains the list of the manifests files that should be included in the deployment. The manifests files should be relative to the root of the repository.
-`configMapGenerator`: This section contains the list of the ConfigMaps that should be included in the deployment. The ConfigMaps should be relative to the root of the repository.
-`secretGenerator`: This section contains the list of the Secrets that should be included in the deployment. The Secrets should be relative to the root of the repository.
### Kustomize resources
This is the most common section in the Kustomization file. The `resources` section contains the list of the manifests files that should be included in the deployment. The manifests files should be relative to the root of the repository.
### Kustomize configMapGenerator
This section contains the list of the ConfigMaps that should be included in the deployment. If we follow the previous example, the ConfigMaps should use the `configmaps` folder in the component folder.
### Kustomize secretGenerator
This section contains the list of the Secrets that should be included in the deployment. The secrets should be in the root of the repository and they should be excluded from the repository in the `.gitignore` file.
The secrets will be added during the CI/CD pipeline execution. The secrets that are not in the repository should be added to the Gitlab CI/CD variables as files. The files should be named with the name of the secret and should contain the secret value.
Latter, during the CI/CD pipeline execution, the secrets will be added to the root of the repository by the k8s-pre-apply.sh. This script takes the secrets from the temporary folder and adds them to the root of the repository.
In summary the steps to add a secret are:
- Create the secret file in the root of the repository, to verify the kustomize configuration. The secret file should avoid characters not allowed in environment variables names such as `-` or `.`.
- Add configuration in the kustomization.yaml file to include the secret file.
- Check the kustomize configuration.
- Add the secret CI/CD setup at the end of the k8s-pre-apply.sh file
- Request a mantainer to create the secret in the Gitlab CI/CD variables.
example of the secret file creation and kustomize configuration:
```bash
cat<<EOF > amoe_redis_secrets
REDIS_PASSWORD=redis_password
REDIS_SERVICE=redis_service
EOF
echo"add amoe_redis_secrets configuration in the kustomization.yaml file"
Once the secret is in the Gitlab CI/CD variables, the k8s-pre-apply.sh script will add the secret to the root of the repository.
## Kustomize check configuration
The Kustomize tool allows you to check the configuration of the Kustomization file. The `kustomize` tool has a command to check the configuration of the Kustomization file. The command is:
