diff --git a/component_integration.md b/component_integration.md index c1a7c4059d7b5fe3c2221b626933cd0f49622a2a..eadbaed02d934f54b419172a33d2a9893794f61f 100644 --- a/component_integration.md +++ b/component_integration.md @@ -1,23 +1,22 @@ # Component Integration -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. +Once a component is developed, and its image published in some accesible registry, we need to integrate it 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 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. +This document contains the guidelines for integrating a new component into the CaaS Framework. The integration is based in merge requests. 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: -- A folder with the component manifests files. -- The required sections in the Kustomization file to include those manifests in the CaaS Framework deployment. +The merge request should be based in the followingpreliminar actions: +- Creation of a folder containing the manifests files for the components. +- Edit the required sections in the Kustomization file in order to include those manifests in the CaaS Framework deployment. In the following sections we explain how to create the merge request with the required information. ## Table of contents - - [Merge request initialisation](#merge-request-initialisation) - [From an issue](#from-an-issue) - - [From a branch](#from-a-branch) + - [From a branch before adding the component](#from-a-branch-before-adding-the-component) + - [(Optional) Download the branch and add the component](#optional-download-the-branch-and-add-the-component) - [From a branch after adding the component](#from-a-branch-after-adding-the-component) -- [(Optional) Download the branch and add the component](#optional-download-the-branch-and-add-the-component) - [Create the component folder](#create-the-component-folder) - [Add the component manifests files](#add-the-component-manifests-files) - [ConfigMaps](#configmaps) @@ -29,14 +28,16 @@ In the following sections we explain how to create the merge request with the re - [Kustomize check configuration](#kustomize-check-configuration) - [Testing the kustomize](#testing-the-kustomize) - [Getting the kubeconfig](#getting-the-kubeconfig) + - [Check the deployment in the kubernetes cluster](#Acces-the-kubernetes-cluster) - [Submit the merge request](#submit-the-merge-request) ## Merge request initialisation -There are many ways to create a merge request in GitLab. In this section we will explain two of them. +There are many ways to create a merge request in GitLab. In this section we will explain three of them. - From an issue (recommended way). -- From a branch. +- From a branch (before adding the component) +- From a branch (after adding the component) ### From an issue @@ -50,30 +51,29 @@ The merge request will be annotated as **draft** so that you can work without th ### 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. when the merge request is accepted. 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**. +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. 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 +#### (Optional) Download the branch and add the component -Another way to work is to clone the repository, add the component in a new branch, push it to the repository, and then create a merge request from that branch. +If you create the branch in the GitLab interface before adding the component, you can download the branch as follows: ```bash git clone git@git.code.tecnalia.com:emerald/private/devops/CaaS-framework.git cd CaaS-framework -echo "Add the component files to the repository" -git checkout -b feature/component_integration -git add . -git commit -m "Add the component files" -git push origin feature/component_integration +git checkout feature/component_integration ``` +### From a branch *after* adding the component -## (Optional) Download the branch and add the component - -This is applicable if you create the branch in the GitLab interface before adding the component. You can download the branch as follows: +Another way to work is to clone the GitLab repository, add the component in a new branch, push it to the repository, and then create a merge request from that branch. ```bash git clone git@git.code.tecnalia.com:emerald/private/devops/CaaS-framework.git cd CaaS-framework -git checkout feature/component_integration +echo "Add the component files to the repository" +git checkout -b feature/component_integration +git add . +git commit -m "Add the component files" +git push origin feature/component_integration ``` ## Create the component folder @@ -81,18 +81,16 @@ Next step to integrate a new component is to create a folder in the [CaaS Framew 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: +There are different types of manifests files, depending on the type of component. The most common types are: - [jobs](https://kubernetes.io/docs/concepts/workloads/controllers/job/) - [services](https://kubernetes.io/docs/concepts/services-networking/service/) - [deployments](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/) - [ingresses](https://kubernetes.io/docs/concepts/services-networking/ingress/) ### Add the component manifests files - 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 named `configmaps` in the component folder. ### Secrets @@ -102,8 +100,7 @@ The Secrets will be created using the `kustomize` tool. The files to be used for  ## Extend the Kustomization file - -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. +The next step is to extend the Kustomization file. The Kustomization file (`kustomize.yaml`) is a YAML file, that contains the list of the manifests files that should be included in the deployment. It is located in the root of the repository of the CaaS Framework. 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/). @@ -152,7 +149,7 @@ echo 'copy_from_cicd_variables "amoe_redis_secrets" "amoe/.secrets/amoe_redis"' Once the secret is placed 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 +## Check the kustomize 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: @@ -171,6 +168,7 @@ kustomize build . | kubectl apply -f - ### Getting the kubeconfig +Yo need the KubeConfig file to access to the Kubernetes cluster from kubctl. 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**. {width=400} @@ -185,26 +183,24 @@ 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. +NOTE: 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 ``` -### 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/. +### Check the deployment in the kubernetes cluster +The EMERALD kubernetes cluster includes a [Rancher server](https://ranchermanager.docs.rancher.com/) to access the cluster. The rancher is available at https://k8so.emerald.digital.tecnalia.dev/. {width=400} {width=400} -There you can access the kubernetes cluster and check the deployment of the component. +There, you can access the kubernetes cluster and check the deployment of the component. {width=400} ## Submit the merge request - -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. +Finally, 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 willmerged it into the main branch. [^k]: https://kubernetes.io/es/