This repository contains Contribution Guidelines for CaaS Framework in emerald project.
This repository contains Contribution Guidelines for CaaS Framework in EMERALD project.
NOTE: These guidelines were written for the project team, and sometimes refer to private repositories not publicly accesible.
## Table of contents
-[Table of contents](#table-of-contents)
...
...
@@ -28,12 +29,11 @@ This repository contains diferent utility guidelines on how to contribute to the
Version: 1.0.0
## Support
If you require support for improving the template, add an [issue](../../../-/issues)to the template and contact the [Owners/Maintainers](../-/project_members?sort=access_level_desc) of the repo.
If you want to improve the guidelines, add an [issue](../../../-/issues) and contact the [Owners/Maintainers](../-/project_members?sort=access_level_desc) of the repo.
Note: remember to change this section to match the support options for your project.
## Roadmap
No future plans for this project appart from improving the template based on feedback.
No future plans for this project apart from improving the guidelines based on your feedback.
## Contributing
In order to contribute to the project, you can [fork](../../../-/forks/new) the repository and create 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.
Once the components are developed and their images published in some accesible registry, the next step is to integrate them into the CaaS Framework. The integration of a new component consist in adding the component manifests files to the repository and extending the Kustomization file to include those manifests files in the deployment.
Once the components are developed and their images published in some accesible registry, next step is to integrate them into the CaaS Framework. The CaaS Framework runs in a [Kubernetes](https://kubernetes.io/) cluster. The integration of a new component consist in 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 purpose of the integration is to submit a merge request. The merge request will be reviewed by the project maintainers and, if accepted, merged into the main branch.
This document contains the guidelines for integrating a new component into the CaaS Framework. The final step of the integration is to submit a merge request. The merge request will be reviewed by the project maintainers and, if accepted, merged into the main branch.
The merge request should contain the following information:
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.
Next step to integrate a new component is to create a folder in the [CaaS Framework repository](https://git.code.tecnalia.com/emerald/private/devops/caas-framework) 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.
E.g., for the amoe component, the folder should be named `amoe` and should contain the manifests files of the component.
The manifests files can be different depending on the component. The most common types are:
The next step is to add the component manifests files to the created folder. 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 examples of names into the `rcm` component.[link?]()
The next step is to add the component manifests files to the created folder. 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 examples into the `rcm` component[folder](https://git.code.tecnalia.com/emerald/private/devops/caas-framework/-/tree/master/rcm?ref_type=heads)
### 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.
It is recommended to create Configmaps using the `kustomize` tool. The contents of the ConfigMaps for the component should be stored in a folder named `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 NOT BE STORED in the repository. The secrets should be added in the component folder in a folder named `.secrets`, that will be excluded from the repository adding the `.secrets/` folder to the `.gitignore` file.
The Secrets will be created using the `kustomize` tool. The files to be used for the secrets generation SHOULD NOT BE STORED in the repository. Fot that, the secrets should be added in the LOCAL component folder, in a folder named `.secrets`, and should be excluded from the repository adding the `.secrets/` folder to the `.gitignore` file.
...
...
@@ -104,7 +105,7 @@ The Secrets will be created using the `kustomize` tool. The files to be used for
The next step is to extend the Kustomization file. The Kustomization file (`kustomization.yaml`) is a YAML file, located in the root of the repository, 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` CLI tool. To install the `kustomize` tool you can follow the instructions in the [official documentation](https://kubectl.docs.kubernetes.io/installation/kustomize/).
To extend the Kustomization file it is recommended to use the [`kustomize`](https://kubernetes.io/docs/reference/kubectl/generated/kubectl_kustomize/) CLI tool. 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`
...
...
@@ -120,18 +121,16 @@ This section contains the list of the ConfigMaps that should be included in the
### 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 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.
The secrets should be added to the GitLab [CI/CD variables](https://docs.gitlab.com/ee/ci/variables/#define-a-cicd-variable-in-the-ui) 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 taken from a temporary folder and will be added to the root of the repository by the `k8s-pre-apply.sh`.)
In summary, the steps to add a secret are:
1. Create the secret file in the component folder, to verify the kustomize configuration.
2. Add configuration in the kustomization.yaml file to include the secret file.
2. Add configuration in the `kustomization.yaml` file to include the secret file.
3. Check the kustomize configuration.
4. Add the secret CI/CD setup at the end of the `k8s-pre-apply.sh` file.
5. Request to some GitLab project [owner or maintainer](https://git.code.tecnalia.com/emerald/private/devops/CaaS-framework/-/project_members) to create the secret in the GitLab CI/CD variables.
Example of the secret file creation and kustomize configuration:
This is an example of the secret file creation and kustomize configuration:
To get the kubeconfig, login into kubernetes https://k8so.emerald.digital.tecnalia.dev/ and download the kubeconfig. **Be aware that the kubeconfig is valid for one month**.
To get the kubeconfig, login into kubernetes https://k8so.emerald.digital.tecnalia.dev/ and download the kubeconfig (see figure below). **Be aware that the kubeconfig is valid for one month**.
The kubeconfig should be stored in the `~/.kube/config` file.
The kubeconfig should be stored in the LOCAL `~/.kube/config` file.
```bash
cat<<EOF > ~/.kube/config
...
...
@@ -186,13 +185,13 @@ EOF
```
{width=50%}
The above is valid for one kubernetes cluster. If you have more than one kubernetes cluster, you can store the kubeconfig in different files and use the `KUBECONFIG` environment variable to select the kubeconfig file.
```bash
kubectl config get-contexts
kubectl config use-context local
```
The above is valid for one kubernetes cluster. If you have more than one kubernetes cluster, you can store the kubeconfig in different files and use the `KUBECONFIG` environment variable to select the kubeconfig file.
### Access the kubernetes cluster
The kubernetes cluster includes a rancher server that allows you to access the kubernetes cluster. The rancher server is available at https://k8so.emerald.digital.tecnalia.dev/.
...
...
@@ -206,4 +205,6 @@ There you can access the kubernetes cluster and check the deployment of the comp
## Submit the merge request
You can submit as much commit as you need to the branch. Once the component is ready for review, you can change the status of the merge request to **ready for review**. The project maintainers will review the merge request and if it is accepted they will add a final commit for semantic versioning and it will be merged into the main branch.
You can submit as many commits as you need to the branch. Once the component is ready for review, you can change the status of the merge request to **ready for review**. The project maintainers will review the merge request and if it is accepted they will add a final commit for semantic versioning and it will be merged into the main branch.
