From 812a4cf34a7e8398d56c9f5e0c48ca02bea537c4 Mon Sep 17 00:00:00 2001 From: Achilleas Pipinellis Date: Tue, 29 Aug 2017 19:03:39 +0200 Subject: [PATCH] Refactor Autodeploy docs - Add a how it works section where Herokuish is mentioned - Make the notes more apparent - Merge the postgres variables section with its parent --- doc/ci/autodeploy/index.md | 91 ++++++++++++++++++++++---------------- 1 file changed, 53 insertions(+), 38 deletions(-) diff --git a/doc/ci/autodeploy/index.md b/doc/ci/autodeploy/index.md index 5272e9e8e68..5c9e11373a2 100644 --- a/doc/ci/autodeploy/index.md +++ b/doc/ci/autodeploy/index.md @@ -1,8 +1,13 @@ # Auto deploy -> [Introduced][mr-8135] in GitLab 8.15. -> Auto deploy is an experimental feature and is not recommended for Production use at this time. -> As of GitLab 9.1, access to the container registry is only available while the Pipeline is running. Restarting a pod, scaling a service, or other actions which require on-going access will fail. On-going secure access is planned for a subsequent release. +>**Notes:** +- [Introduced][mr-8135] in GitLab 8.15. +- Auto deploy is an experimental feature and is not recommended for Production + use at this time. +- As of GitLab 9.1, access to the Container Registry is only available while + the Pipeline is running. Restarting a pod, scaling a service, or other actions + which require on-going access will fail. On-going secure access is planned for + a subsequent release. Auto deploy is an easy way to configure GitLab CI for the deployment of your application. GitLab Community maintains a list of `.gitlab-ci.yml` @@ -11,9 +16,19 @@ powering them. These scripts are responsible for packaging your application, setting up the infrastructure and spinning up necessary services (for example a database). -You can use [project services][project-services] to store credentials to -your infrastructure provider and they will be available during the -deployment. +## How it works + +The Autodeploy templates are based on the [kubernetes-deploy][kube-deploy] +project which is used to simplify the deployment process to Kubernetes by +providing intelligent `build`, `deploy` and `destroy` commands which you can +use in your `.gitlab-ci.yml` as-is. It uses [Herokuish](https://github.com/gliderlabs/herokuish), +which uses [Heroku buildpacks](https://devcenter.heroku.com/articles/buildpacks) +to do some of the work, plus some of GitLab's own tools to package it all up. For +your convenience, a [Docker image][kube-image] is also provided. + +You can use the [Kubernetes project service](../../user/project/integrations/kubernetes.md) +to store credentials to your infrastructure provider and they will be available +during the deployment. ## Quick start @@ -26,30 +41,28 @@ The list of supported auto deploy templates is available in the ## Configuration +>**Note:** +In order to understand why the following steps are required, read the +[how it works](#how-it-works) section. + +To configure Autodeploy, you will need to: + 1. Enable a deployment [project service][project-services] to store your -credentials. For example, if you want to deploy to OpenShift you have to -enable [Kubernetes service][kubernetes-service]. -1. Configure GitLab Runner to use Docker or Kubernetes executor with -[privileged mode enabled][docker-in-docker]. + credentials. For example, if you want to deploy to OpenShift you have to + enable [Kubernetes service][kubernetes-service]. +1. Configure GitLab Runner to use the + [Docker or Kubernetes executor](https://docs.gitlab.com/runner/executors/) with + [privileged mode enabled][docker-in-docker]. 1. Navigate to the "Project" tab and click "Set up auto deploy" button. ![Auto deploy button](img/auto_deploy_button.png) 1. Select a template. ![Dropdown with auto deploy templates](img/auto_deploy_dropdown.png) 1. Commit your changes and create a merge request. 1. Test your deployment configuration using a [Review App][review-app] that was -created automatically for you. + created automatically for you. ## Using the Kubernetes deploy example project with Nginx -The Autodeploy templates are based on the [kubernetes-deploy][kube-deploy] -project which is used to simplify the deployment process to Kubernetes by -providing intelligent `build`, `deploy` and `destroy` commands which you can -use in your `.gitlab-ci.yml` as-is. It uses Heroku'ish build packs to do some -of the work, plus some of GitLab's own tools to package it all up. For your -convenience, a [Docker image][kube-image] is also provided. - ---- - A simple example would be the deployment of Nginx on Kubernetes. Consider a `nginx-deployment.yaml` file in your project with contents: @@ -77,7 +90,8 @@ spec: ``` The important part is where we set up `app: __CI_ENVIRONMENT_SLUG__`. As you'll -see later this is replaced by the [`CI_ENVIRONMENT_SLUG` env variable][variables]. +see later this is replaced by the +[`CI_ENVIRONMENT_SLUG` env variable](../variables/README.md#predefined-variables-environment-variables). The `.gitlab-ci.yml` would be: @@ -118,7 +132,7 @@ Next, we replace `__CI_ENVIRONMENT_SLUG__` with the content of the Finally, the Nginx pod is created from the definition of the `nginx-deployment.yaml` file. -## Private Project Support +## Private project support > Experimental support [introduced][mr-2] in GitLab 9.1. @@ -126,7 +140,7 @@ When a project has been marked as private, GitLab's [Container Registry][contain After the pipeline completes, Kubernetes will no longer be able to access the container registry. Restarting a pod, scaling a service, or other actions which require on-going access to the registry will fail. On-going secure access is planned for a subsequent release. -## PostgreSQL Database Support +## PostgreSQL database support > Experimental support [introduced][mr-8] in GitLab 9.1. @@ -134,27 +148,13 @@ In order to support applications that require a database, [PostgreSQL][postgresq PostgreSQL provisioning can be disabled by setting the variable `DISABLE_POSTGRES` to `"yes"`. -### PostgreSQL Variables +The following PostgreSQL variables are supported: 1. `DISABLE_POSTGRES: "yes"`: disable automatic deployment of PostgreSQL 1. `POSTGRES_USER: "my-user"`: use custom username for PostgreSQL 1. `POSTGRES_PASSWORD: "password"`: use custom password for PostgreSQL 1. `POSTGRES_DB: "my database"`: use custom database name for PostgreSQL -[mr-8135]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8135 -[mr-2]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/2 -[mr-8]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/8 -[project-settings]: https://docs.gitlab.com/ce/public_access/public_access.html -[project-services]: ../../user/project/integrations/project_services.md -[auto-deploy-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml/tree/master/autodeploy -[kubernetes-service]: ../../user/project/integrations/kubernetes.md -[docker-in-docker]: ../docker/using_docker_build.md#use-docker-in-docker-executor -[review-app]: ../review_apps/index.md -[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry" -[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project" -[container-registry]: https://docs.gitlab.com/ce/user/project/container_registry.html -[postgresql]: https://www.postgresql.org/ - ## Auto Monitoring > Introduced in [GitLab 9.5](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/13438). @@ -179,3 +179,18 @@ If you have installed GitLab using a different method: 1. [Deploy Prometheus](../../user/project/integrations/prometheus.md#configuring-your-own-prometheus-server-within-kubernetes) into your Kubernetes cluster 1. If you would like response metrics, ensure you are running at least version 0.9.0 of NGINX Ingress and [enable Prometheus metrics](https://github.com/kubernetes/ingress/blob/master/examples/customization/custom-vts-metrics/nginx/nginx-vts-metrics-conf.yaml). 1. Finally, [annotate](https://kubernetes.io/docs/concepts/overview/working-with-objects/annotations/) the NGINX Ingress deployment to be scraped by Prometheus using `prometheus.io/scrape: "true"` and `prometheus.io/port: "10254"`. + +[mr-8135]: https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/8135 +[mr-2]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/2 +[mr-8]: https://gitlab.com/gitlab-examples/kubernetes-deploy/merge_requests/8 +[project-settings]: https://docs.gitlab.com/ce/public_access/public_access.html +[project-services]: ../../user/project/integrations/project_services.md +[auto-deploy-templates]: https://gitlab.com/gitlab-org/gitlab-ci-yml/tree/master/autodeploy +[kubernetes-service]: ../../user/project/integrations/kubernetes.md +[docker-in-docker]: ../docker/using_docker_build.md#use-docker-in-docker-executor +[review-app]: ../review_apps/index.md +[kube-image]: https://gitlab.com/gitlab-examples/kubernetes-deploy/container_registry "Kubernetes deploy Container Registry" +[kube-deploy]: https://gitlab.com/gitlab-examples/kubernetes-deploy "Kubernetes deploy example project" +[container-registry]: https://docs.gitlab.com/ce/user/project/container_registry.html +[postgresql]: https://www.postgresql.org/ +