diff options
Diffstat (limited to 'doc/topics/autodevops/quick_start_guide.md')
| -rw-r--r-- | doc/topics/autodevops/quick_start_guide.md | 352 |
1 files changed, 252 insertions, 100 deletions
diff --git a/doc/topics/autodevops/quick_start_guide.md b/doc/topics/autodevops/quick_start_guide.md index 61c04f3d9bb..07ba61b48e6 100644 --- a/doc/topics/autodevops/quick_start_guide.md +++ b/doc/topics/autodevops/quick_start_guide.md @@ -1,143 +1,295 @@ -# Auto DevOps: quick start guide +# Getting started with Auto DevOps -> [Introduced][ce-37115] in GitLab 10.0. +This is a step-by-step guide that will help you deploy a project hosted on +GitLab.com to Google Kubernetes Engine, using [Auto DevOps](index.md). -This is a step-by-step guide to deploying a project hosted on GitLab.com to -Google Cloud, using Auto DevOps. +We will use the Kubernetes integration that GitLab provides, so you won't have +to create a Kubernetes cluster manually using the GCP console. -We made a minimal [Ruby -application](https://gitlab.com/auto-devops-examples/minimal-ruby-app) to use -as an example for this guide. It contains two main files: +## Configuring your Google account -* `server.rb` - our application. It will start an HTTP server on port 5000 and - render "Hello, world!" -* `Dockerfile` - to build our app into a container image. It will use a ruby - base image and run `server.rb` +Before creating and connecting your Kubernetes cluster to your GitLab project, +you have to set up your Google Cloud account. If you don't already have one, go +and create it at https://console.cloud.google.com. If you already have a +Google account that you use to access Gmail, etc., you can use it to sign in +the Google Cloud. -## Fork sample project on GitLab.com +1. Follow the steps as outlined in the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin) + in order for the required APIs and related services to be enabled. +1. Make sure you have created a [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account). -Let’s start by forking our sample application. Go to [the project -page](https://gitlab.com/auto-devops-examples/minimal-ruby-app) and press the -**Fork** button. Soon you should have a project under your namespace with the -necessary files. +TIP: **Tip:** +Every new Google Cloud Platform (GCP) account receives [$300 in credit](https://console.cloud.google.com/freetrial), +and in partnership with Google, GitLab is able to offer an additional $200 for new GCP accounts to get started with GitLab's +Google Kubernetes Engine Integration. All you have to do is [follow this link](https://goo.gl/AaJzRW) and apply for credit. -You can also start a new project from a -[GitLab project template](https://gitlab.com/gitlab-org/project-templates) if -you want to use a different language. +## Creating a new project from a template -## Setup your own cluster on Google Kubernetes Engine +We will use one of GitLab's project templates to get started. AS the name suggests, +those projects provide a barebone of an application built on some well known frameworks. -If you do not already have a Google Cloud account, create one at -https://console.cloud.google.com. +1. Find the plus icon (**+**) at the top of the navigation bar, click it and select + **New project**. +1. Go to the **Create from template** tab where you can choose among a Ruby on + Rails, a Spring, or a NodeJS Express project. For the sake of the example + let's use the Ruby on Rails template. -Visit the [**Kubernetes Engine**](https://console.cloud.google.com/kubernetes/list) -tab and create a new cluster. You can change the name and leave the rest of the -default settings. Once you have your cluster running, you need to connect to the -cluster by following the Google interface. +  -## Connect to Kubernetes cluster +1. Give your project a name, optionally a description, and make it public so that + you can take advantage of the features available in the + [GitLab Gold plan](https://about.gitlab.com/pricing/#gitlab-com). -You need to have the Google Cloud SDK installed. e.g. -On macOS, install [homebrew](https://brew.sh): +  -1. Install Brew Caskroom: `brew install caskroom/cask/brew-cask` -2. Install Google Cloud SDK: `brew cask install google-cloud-sdk` -3. Add `kubectl` with: `gcloud components install kubectl` -4. Log in: `gcloud auth login` +1. Finally, click on the **Create project** button. -Now go back to the Google interface, find your cluster, follow the instructions -under "Connect to the cluster" and open the Kubernetes Dashboard. It will look -something like: +Now that the project is created, the next step is to create the Kubernetes cluster +under which this application will be deployed. -```sh -gcloud container clusters get-credentials ruby-autodeploy \ --zone europe-west2-c --project api-project-XXXXXXX -``` +## Creating a Kubernetes cluster -Finally, run `kubectl proxy`. +One thing you should notice after you created the project is the **Add Kubernetes cluster** +button on the project's landing page. Go ahead and click it. - + -## Copy credentials to GitLab.com project +TIP: **Tip:** +Another way is to navigate to **Operations > Kubernetes** and click on +**Add Kubernetes cluster**. -Once you have the Kubernetes Dashboard interface running, you should visit -**Secrets** under the "Config" section. There, you should find the settings we -need for GitLab integration: `ca.crt` and token. +From there on, let's see how to create a new Kubernetes cluster on GKE: - +1. Choose **Create on Google Kubernetes Engine**. -You need to copy-paste the `ca.crt` and token into your project on GitLab.com in -the Kubernetes integration page under project -**Settings > Integrations > Project services > Kubernetes**. Don't actually copy -the namespace though. Each project should have a unique namespace, and by leaving -it blank, GitLab will create one for you. +  - +1. Sign in with Google. -For the API URL, you should use the "Endpoint" IP from your cluster page on -Google Cloud Platform. +  -## Expose application to the world +1. Connect with your Google account and press **Allow** when asked (this will + be shown only the first time you connect GitLab with your Google account). -In order to be able to visit your application, you need to install an NGINX -ingress controller and point your domain name to its external IP address. Let's -see how that's done. +  -### Set up Ingress controller +1. The last step is to fill in the cluster details. Give it a name, leave the + environment scope as is, and choose the GCP project under which the cluster + will be created (if you followed the instructions when you + [configured your Google account](#configuring-your-google-account), a project + should have been created for you). Next, choose the + [region/zone](https://cloud.google.com/compute/docs/regions-zones/) under which the + cluster will be created, enter the number of nodes you want it to have, and + finally choose their [machine type](https://cloud.google.com/compute/docs/machine-types). -You’ll need to make sure you have an ingress controller. If you don’t have one, do: +  -```sh -brew install kubernetes-helm -helm init -helm install --name ruby-app stable/nginx-ingress -``` +1. Once ready, hit the **Create Kubernetes cluster** button. -This should create several services including `ruby-app-nginx-ingress-controller`. -You can list your services by running `kubectl get svc` to confirm that. +After a couple of minutes, the cluster will be created. You can also see its +status on your [GCP dashboard](https://console.cloud.google.com/kubernetes). -### Point DNS at Cluster IP +The next step is to install some applications on your cluster that are needed +to take full advantage of Auto DevOps. -Find out the external IP address of the `ruby-app-nginx-ingress-controller` by -running: +## Installing Helm, Ingress and Prometheus -```sh -kubectl get svc ruby-app-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' -``` +GitLab's Kubernetes integration comes with some +[pre-defined applications](../../user/project/clusters/index.md#installing-applications) +for you to install. + + + +The first one to install is Helm Tiller, a package manager for Kubernetes, which +is needed in order to install the rest of the applications. Go ahead and click +its **Install** button. + +Once it's installed, the other applications that rely on it will have their **Install** +button enabled. For this guide, we need Ingress and Prometheus. Ingress provides +load balancing, SSL termination, and name-based virtual hosting, using NGINX behind +the scenes. Prometheus is an open-source monitoring and alerting system that we'll +use to supervise the deployed application. We will not install GitLab Runner as +we'll use the shared Runners that GitLab.com provides. + +After the Ingress is installed, wait a few seconds and copy the IP address that +will show up, we'll use in the next step when enabling Auto DevOps. + +## Enabling Auto DevOps + +Now that the Kubernetes cluster is set up and ready, let's enable Auto DevOps. + +1. First, navigate to **Settings > CI/CD > Auto DevOps**. + +1. Select **Enable Auto DevOps**. +1. Add in your base **Domain** by using the one GitLab suggests. Note that + generally, you would associate the IP address with a domain name on your + registrar's settings. In this case, for the sake of the guide, we will use + an alternative DNS that will map any domain name of the scheme + `anything.ip_address.nip.io` to the corresponding `ip_address`. For example, + if the IP address of the Ingress is `1.2.3.4`, the domain name to fill in + would be `1.2.3.4.nip.io`. +1. Lastly, let's select the [continuous deployment strategy](index.md#deployment-strategy) + which will automatically deploy the application to production once the pipeline + successfully runs on `master` branch. +1. Hit **Save changes** for the changes to take effect. + +  + +Once you complete all the above and save your changes, a new pipeline will be +automatically created. Go to **CI/CD > Pipelines** to check it out. + + + +In the next section we'll break down the pipeline and explain what each job does. + +## Deploying the application + +So, by now you should see the pipeline running, but what is it running exactly? + +To navigate inside the pipeline, click on its status badge (it should say running) +The pipeline is split into 4 stages, each running a couple of jobs. + + + +In the **build** stage, the application is built into a Docker image and then +uploaded to your project's [Container Registry](../../user/project/container_registry.md) ([Auto Build](index.md#auto-build)). + +In the **test** stage, GitLab runs various checks on the application: + +- The `test` job runs unit and integration tests by detecting the language and + framework ([Auto Test](index.md#auto-test)) +- The `code_quality` job checks the code quality and is allowed to fail + ([Auto Code Quality](index.md#auto-code-quality)) **[STARTER]** +- The `container_scanning` job checks the Docker container if it has any + vulnerabilities and is allowed to fail ([Auto Container Scanning](index.md#auto-container-scanning)) +- The `dependency_scanning` job checks if the application has any dependencies + susceptible to vulnerabilities and is allowed to fail ([Auto Dependency Scanning](index.md#auto-dependency-scanning)) **[ULTIMATE]** +- The `sast` job runs static analysis on the current code and checks for potential + security issues and is allowed to fail([Auto SAST](index.md#auto-sast)) **[ULTIMATE]** +- The `license_management` job searches the application's dependencies for their + license and is allowed to fail ([Auto License Management](index.md#auto-license-management)) **[ULTIMATE]** NOTE: **Note:** -If your ingress controller has been installed in a different way, you can find -how to get the external IP address in the -[Cluster documentation](../../user/project/clusters/index.md#getting-the-external-ip-address). +As you might have noticed, all jobs except `test` are allowed to fail in the +test stage. + +The **production** stage is run after the tests and checks finish, and it automatically +deploys the application in Kubernetes ([Auto Deploy](index.md#auto-deploy)). + +Lastly, in the **performance** stage, some performance tests will run +on the deployed application +([Auto Browser Performance Testing](index.md#auto-browser-performance-testing)). **[PREMIUM]** + +--- + +The URL for the deployed application can be found under the **Environments** +page where you can also monitor your application. Let's explore that. + +### Monitoring + +Now that the application is successfully deployed, let's navigate to its +website, by first going to **Operations > Environments**. + + + +This is the **Environments** where you can see some details about the deployed +applications. At the upper right or the production environment, you should see +some icons: + +- The first one will take you to the URL of the application that is deployed in + production. It's a very simple page, but the purpose is that it works! +- The next icon with the little graph will take you to the metrics page where + prometheus collects data about the Kubernetes cluster and how the application + affects it (in terms of memory/CPU usage, latency etc.). -Use this IP address to configure your DNS. This part heavily depends on your -preferences and domain provider. But in case you are not sure, just create an -A record with a wildcard host like `*.<your-domain>`. +  -Use `nslookup minimal-ruby-app-staging.<yourdomain>` to confirm that domain is -assigned to the cluster IP. +- The third icon is the [web terminal](../../ci/environments.md#web-terminals) + and it will open a terminal session right inside the container where the + application is running. -## Set up Auto DevOps +Right below, there is the +[Deploy Board](https://docs.gitlab.com/ee/user/project/deploy_boards.md). +The squares represent pods in your Kubernetes cluster that are associated with +the given environment. Hovering above each square you can see the state of a +deployment and clicking on the square will take you to the pod's logs page. -In your GitLab.com project, go to **Settings > CI/CD** and find the Auto DevOps -section. Select "Enable Auto DevOps", add in your base domain, and save. +TIP: **Tip:** +There is only one pod hosting the application at the moment, but you can add +more pods by defining the [`REPLICAS` variable](index.md#environment-variables) +under **Settings > CI/CD > Variables**. -Next, a pipeline needs to be triggered. Since the test project doesn't have a -`.gitlab-ci.yml`, you need to either push a change to the repository or -manually visit `https://gitlab.com/<username>/minimal-ruby-app/pipelines/new`, -where `<username>` is your username. +### Working with branches -This will create a new pipeline with several jobs: `build`, `test`, `code_quality`, -and `production`. The `build` job will create a Docker image with your new -change and push it to the Container Registry. The `test` job will test your -changes, whereas the `code_quality` job will run static analysis on your changes. -Finally, the `production` job will deploy your changes to a production application. +Following the [GitLab flow](../../workflow/gitlab_flow.md#working-with-feature-branches) +let's create a feature branch that will add some content to the application. -Once the deploy job succeeds you should be able to see your application by -visiting the Kubernetes dashboard. Select the namespace of your project, which -will look like `minimal-ruby-app-23`, but with a unique ID for your project, -and your app will be listed as "production" under the Deployment tab. +Under your repository, navigate to the following file: `app/views/welcome/index.html.erb`. +By now, it should only contain a paragraph: `<p>You're on Rails!</p>`, so let's +start adding content. Let's use GitLab's [Web IDE]() to make the change. Once +you're on the Web IDE, make the following change: -Once its ready, just visit `http://minimal-ruby-app.example.com` to see the -famous "Hello, world!"! +```html +<p>You're on Rails! Powered by GitLab Auto DevOps.</p> +``` + +Stage the file, add a commit message, and create a new branch and a merge request +by clicking **Commit**. + + + +Once you submit the merge request, you'll see the pipeline running. This will +run all the jobs as [described previously](#deploying-the-application), as well +a few more that run only on branches other than `master`. + + + +After a few minutes you'll realize that there was a failure in a test. +That means that there's a test that was broken when we made the change. +Navigating in the `test` job that failed, you can see what the broken test is: + +``` +Failure: +WelcomeControllerTest#test_should_get_index [/app/test/controllers/welcome_controller_test.rb:7]: +<You're on Rails!> expected but was +<You're on Rails! Powered by GitLab Auto DevOps.>.. +Expected 0 to be >= 1. + +bin/rails test test/controllers/welcome_controller_test.rb:4 +``` -[ce-37115]: https://gitlab.com/gitlab-org/gitlab-ce/issues/37115 +Let's fix that: + +1. Back to the merge request, click the **Web IDE** button. +1. Find the `test/controllers/welcome_controller_test.rb` file and open it. +1. Change line 7 to say `You're on Rails! Powered by GitLab Auto DevOps.` +1. Click **Commit**. +1. On your left, under "Unstaged changes", click the little checkmark icon + to stage the changes. +1. Write a commit message and hit **Commit** + +Now, if you go back to the merge request you should see not only the test passing, +but the application deployed as a [review app](index.md#auto-review-apps). You +can visit it by following the URL in the merge request. The changes that we +previously made should be there. + + + +Once you merge the merge request, the pipeline will run on the `master` branch, +and the application will be eventually deployed straight to production. + +## Conclusion + +By now, you should have gained a solid understanding of how Auto DevOps works. +We started from building and testing to deploying and monitoring an application +all within GitLab. In spite of its auto nature, this doesn't mean that you can't +configure and customize Auto DevOps to fit your workflow. Here are a few +interesting links: + +1. [Auto DevOps](index.md) +1. [Multiple Kubernetes clusters](index.md#using-multiple-kubernetes-clusters) **[PREMIUM]** +1. [Incremental rollout to production](index.md#incremental-rollout-to-production) **[PREMIUM]** +1. [Disable jobs you don't need with environment variables](index.md#environment-variables) +1. [Use a static IP for your cluster](../../user/project/clusters/index.md#using-a-static-ip) +1. [Use your own buildpacks to build your application](index.md#custom-buildpacks) +1. [Prometheus monitoring](../../user/project/integrations/prometheus.md) |