diff options
Diffstat (limited to 'doc/user/project/clusters')
15 files changed, 348 insertions, 323 deletions
diff --git a/doc/user/project/clusters/img/k8s_cluster_monitoring.png b/doc/user/project/clusters/img/k8s_cluster_monitoring.png Binary files differnew file mode 100644 index 00000000000..e449893a606 --- /dev/null +++ b/doc/user/project/clusters/img/k8s_cluster_monitoring.png diff --git a/doc/user/project/clusters/img/kubernetes_pod_logs.png b/doc/user/project/clusters/img/kubernetes_pod_logs.png Binary files differnew file mode 100644 index 00000000000..e664a47386a --- /dev/null +++ b/doc/user/project/clusters/img/kubernetes_pod_logs.png diff --git a/doc/user/project/clusters/img/pod_logs_deploy_board.png b/doc/user/project/clusters/img/pod_logs_deploy_board.png Binary files differnew file mode 100644 index 00000000000..7f83382968b --- /dev/null +++ b/doc/user/project/clusters/img/pod_logs_deploy_board.png diff --git a/doc/user/project/clusters/index.md b/doc/user/project/clusters/index.md index e601d7b2ccc..dc21db603d6 100644 --- a/doc/user/project/clusters/index.md +++ b/doc/user/project/clusters/index.md @@ -19,8 +19,10 @@ or provide the credentials to an [existing Kubernetes cluster](#adding-an-existi NOTE: **Note:** From [GitLab 11.6](https://gitlab.com/gitlab-org/gitlab-ce/issues/34758) you -can also associate a Kubernetes cluster to your groups. Learn more about -[group Kubernetes clusters](../../group/clusters/index.md). +can also associate a Kubernetes cluster to your groups and from +[GitLab 11.11](https://gitlab.com/gitlab-org/gitlab-ce/issues/39840), +to the GitLab instance. Learn more about [group-level](../../group/clusters/index.md) +and [instance-level](../../instance/clusters/index.md) Kubernetes clusters. ## Adding and creating a new GKE cluster via GitLab @@ -41,7 +43,7 @@ integration, make sure the following requirements are met: - A [billing account](https://cloud.google.com/billing/docs/how-to/manage-billing-account) is set up and you have permissions to access it. -- The Kubernetes Engine API is enabled. Follow the steps as outlined in the +- The Kubernetes Engine API and related service are enabled. It should work immediately but may take up to 10 minutes after you create a project. For more information see the ["Before you begin" section of the Kubernetes Engine docs](https://cloud.google.com/kubernetes-engine/docs/quickstart#before-you-begin). ### Creating the cluster @@ -69,11 +71,21 @@ new Kubernetes cluster to your project: - **Number of nodes** - Enter the number of nodes you wish the cluster to have. - **Machine type** - The [machine type](https://cloud.google.com/compute/docs/machine-types) of the Virtual Machine instance that the cluster will be based on. + - **RBAC-enabled cluster** - Leave this checked if using default GKE creation options, see the [RBAC section](#rbac-cluster-resources) for more information. + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. 1. Finally, click the **Create Kubernetes cluster** button. After a couple of minutes, your cluster will be ready to go. You can now proceed to install some [pre-defined applications](#installing-applications). +NOTE: **Note:** +GitLab requires basic authentication enabled and a client certificate issued for +the cluster in order to setup an [initial service +account](#access-controls). Starting from [GitLab +11.10](https://gitlab.com/gitlab-org/gitlab-ce/issues/58208), the cluster +creation process will explicitly request that basic authentication and +client certificate is enabled. + ## Adding an existing Kubernetes cluster To add an existing Kubernetes cluster to your project: @@ -87,19 +99,25 @@ To add an existing Kubernetes cluster to your project: 1. Click **Add an existing Kubernetes cluster** and fill in the details: - **Kubernetes cluster name** (required) - The name you wish to give the cluster. - **Environment scope** (required) - The - [associated environment](#setting-the-environment-scope) to this cluster. + [associated environment](#setting-the-environment-scope-premium) to this cluster. - **API URL** (required) - It's the URL that GitLab uses to access the Kubernetes API. Kubernetes exposes several APIs, we want the "base" URL that is common to all of them, e.g., `https://kubernetes.example.com` rather than `https://kubernetes.example.com/api/v1`. + + Get the API URL by running this command: + + ```sh + kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}' + ``` - **CA certificate** (required) - A valid Kubernetes certificate is needed to authenticate to the EKS cluster. We will use the certificate created by default. - - List the secrets with `kubectl get secrets`, and one should named similar to + - List the secrets with `kubectl get secrets`, and one should named similar to `default-token-xxxxx`. Copy that token name for use below. - - Get the certificate by running this command: + - Get the certificate by running this command: - ```sh - kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode - ``` + ```sh + kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode + ``` - **Token** - GitLab authenticates against Kubernetes using service tokens, which are scoped to a particular `namespace`. @@ -109,15 +127,28 @@ To add an existing Kubernetes cluster to your project: 1. Create a file called `gitlab-admin-service-account.yaml` with contents: - ```yaml - apiVersion: v1 - kind: ServiceAccount - metadata: - name: gitlab-admin - namespace: kube-system - ``` - - 2. Apply the service account to your cluster: + ```yaml + apiVersion: v1 + kind: ServiceAccount + metadata: + name: gitlab-admin + namespace: kube-system + --- + apiVersion: rbac.authorization.k8s.io/v1beta1 + kind: ClusterRoleBinding + metadata: + name: gitlab-admin + roleRef: + apiGroup: rbac.authorization.k8s.io + kind: ClusterRole + name: cluster-admin + subjects: + - kind: ServiceAccount + name: gitlab-admin + namespace: kube-system + ``` + + 1. Apply the service account and cluster role binding to your cluster: ```bash kubectl apply -f gitlab-admin-service-account.yaml @@ -125,69 +156,44 @@ To add an existing Kubernetes cluster to your project: Output: - ```bash - serviceaccount "gitlab-admin" created - ``` - - 3. Create a file called `gitlab-admin-cluster-role-binding.yaml` with contents: - - ```yaml - apiVersion: rbac.authorization.k8s.io/v1beta1 - kind: ClusterRoleBinding - metadata: - name: gitlab-admin - roleRef: - apiGroup: rbac.authorization.k8s.io - kind: ClusterRole - name: cluster-admin - subjects: - - kind: ServiceAccount - name: gitlab-admin - namespace: kube-system - ``` - - 4. Apply the cluster role binding to your cluster: - - ```bash - kubectl apply -f gitlab-admin-cluster-role-binding.yaml - ``` - - Output: - ```bash + serviceaccount "gitlab-admin" created clusterrolebinding "gitlab-admin" created ``` - 5. Retrieve the token for the `gitlab-admin` service account: + 1. Retrieve the token for the `gitlab-admin` service account: ```bash kubectl -n kube-system describe secret $(kubectl -n kube-system get secret | grep gitlab-admin | awk '{print $1}') ``` - Copy the `<authentication_token>` value from the output: + Copy the `<authentication_token>` value from the output: - ```yaml - Name: gitlab-admin-token-b5zv4 - Namespace: kube-system - Labels: <none> - Annotations: kubernetes.io/service-account.name=gitlab-admin - kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 + ```yaml + Name: gitlab-admin-token-b5zv4 + Namespace: kube-system + Labels: <none> + Annotations: kubernetes.io/service-account.name=gitlab-admin + kubernetes.io/service-account.uid=bcfe66ac-39be-11e8-97e8-026dce96b6e8 - Type: kubernetes.io/service-account-token + Type: kubernetes.io/service-account-token + + Data + ==== + ca.crt: 1025 bytes + namespace: 11 bytes + token: <authentication_token> + ``` - Data - ==== - ca.crt: 1025 bytes - namespace: 11 bytes - token: <authentication_token> - ``` - NOTE: **Note:** For GKE clusters, you will need the `container.clusterRoleBindings.create` permission to create a cluster role binding. You can follow the [Google Cloud documentation](https://cloud.google.com/iam/docs/granting-changing-revoking-access) to grant access. + + - **GitLab-managed cluster** - Leave this checked if you want GitLab to manage namespaces and service accounts for this cluster. See the [Managed clusters section](#gitlab-managed-clusters) for more information. + - **Project namespace** (optional) - You don't have to fill it in; by leaving it blank, GitLab will create one for you. Also: - Each project should have a unique namespace. @@ -203,14 +209,6 @@ To add an existing Kubernetes cluster to your project: After a couple of minutes, your cluster will be ready to go. You can now proceed to install some [pre-defined applications](#installing-applications). -To determine the: - -- API URL, run `kubectl cluster-info | grep 'Kubernetes master' | awk '/http/ {print $NF}'`. -- Token: - 1. List the secrets by running: `kubectl get secrets`. Note the name of the secret you need the token for. - 1. Get the token for the appropriate secret by running: `kubectl get secret <SECRET_NAME> -o jsonpath="{['data']['token']}" | base64 --decode`. -- CA certificate, run `kubectl get secret <secret name> -o jsonpath="{['data']['ca\.crt']}" | base64 --decode`. - ## Security implications CAUTION: **Important:** @@ -222,78 +220,112 @@ functionalities needed to successfully build and deploy a containerized application. Bear in mind that the same credentials are used for all the applications running on the cluster. +## Gitlab-managed clusters + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/22011) in GitLab 11.5. +> Became [optional](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/26565) in GitLab 11.11. + +NOTE: **Note:** +Only available when creating clusters. Existing clusters not managed by GitLab +cannot become GitLab-managed later. + +You can choose to allow GitLab to manage your cluster for you. If your cluster is +managed by GitLab, resources for your projects will be automatically created. See the +[Access controls](#access-controls) section for details on which resources will +be created. + +If you choose to manage your own cluster, project-specific resources will not be created +automatically. If you are using [Auto DevOps](../../../topics/autodevops/index.md), you will +need to explicitly provide the `KUBE_NAMESPACE` [deployment variable](#deployment-variables) +that will be used by your deployment jobs, otherwise a namespace will be created for you. + +NOTE: **Note:** +If you [install applications](#installing-applications) on your cluster, GitLab will create +the resources required to run these even if you have chosen to manage your own cluster. + ## Base domain > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24580) in GitLab 11.8. -Domains at the cluster level permit support for multiple domains -per [multiple Kubernetes clusters](#multiple-kubernetes-clusters-premium). When specifying a domain, -this will be automatically set as an environment variable (`KUBE_INGRESS_BASE_DOMAIN`) during -the [Auto DevOps](../../../topics/autodevops/index.md) stages. +NOTE: **Note:** +You do not need to specify a base domain on cluster settings when using GitLab Serverless. The domain in that case +will be specified as part of the Knative installation. See [Installing Applications](#installing-applications). + +Specifying a base domain will automatically set `KUBE_INGRESS_BASE_DOMAIN` as an environment variable. +If you are using [Auto DevOps](../../../topics/autodevops/index.md), this domain will be used for the different +stages. For example, Auto Review Apps and Auto Deploy. + +The domain should have a wildcard DNS configured to the Ingress IP address. After ingress has been installed (see [Installing Applications](#installing-applications)), +you can either: -The domain should have a wildcard DNS configured to the Ingress IP address. +- Create an `A` record that points to the Ingress IP address with your domain provider. +- Enter a wildcard DNS address using a service such as nip.io or xip.io. For example, `192.168.1.1.xip.io`. ## Access controls -When creating a cluster in GitLab, you will be asked if you would like to create an -[Attribute-based access control (ABAC)](https://kubernetes.io/docs/admin/authorization/abac/) cluster, or -a [Role-based access control (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/) one. +When creating a cluster in GitLab, you will be asked if you would like to create either: -NOTE: **Note:** -[RBAC](#role-based-access-control-rbac) is recommended and the GitLab default. +- An [Attribute-based access control (ABAC)](https://kubernetes.io/docs/admin/authorization/abac/) cluster. +- A [Role-based access control (RBAC)](https://kubernetes.io/docs/admin/authorization/rbac/) cluster. -Whether [ABAC](#attribute-based-access-control-abac) or [RBAC](#role-based-access-control-rbac) is enabled, -GitLab will create the necessary service accounts and privileges in order to install and run -[GitLab managed applications](#installing-applications): +NOTE: **Note:** +[RBAC](#rbac-cluster-resources) is recommended and the GitLab default. -- If GitLab is creating the cluster, a `gitlab` service account with - `cluster-admin` privileges will be created in the `default` namespace, - which will be used by GitLab to manage the newly created cluster. +GitLab creates the necessary service accounts and privileges to install and run +[GitLab managed applications](#installing-applications). When GitLab creates the cluster: +- A `gitlab` service account with `cluster-admin` privileges is created in the `default` namespace + to manage the newly created cluster. - A project service account with [`edit` privileges](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) - will be created in the project namespace (also created by GitLab), which will - be used in [deployment jobs](#deployment-variables). + is created in the GitLab-created project namespace for [deployment jobs](#deployment-variables). NOTE: **Note:** Restricted service account for deployment was [introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/51716) in GitLab 11.5. -- When you install Helm Tiller into your cluster, the `tiller` service account - will be created with `cluster-admin` privileges in the `gitlab-managed-apps` - namespace. This service account will be added to the installed Helm Tiller and will - be used by Helm to install and run [GitLab managed applications](#installing-applications). - Helm Tiller will also create additional service accounts and other resources for each - installed application. Consult the documentation of the Helm charts for each application - for details. +When you install Helm into your cluster, the `tiller` service account +is created with `cluster-admin` privileges in the `gitlab-managed-apps` +namespace. This service account will be added to the installed Helm Tiller and will +be used by Helm to install and run [GitLab managed applications](#installing-applications). +Helm will also create additional service accounts and other resources for each +installed application. Consult the documentation of the Helm charts for each application +for details. If you are [adding an existing Kubernetes cluster](#adding-an-existing-kubernetes-cluster), ensure the token of the account has administrator privileges for the cluster. -The following sections summarize which resources will be created on ABAC/RBAC clusters. +The resources created by GitLab differ depending on the type of cluster. + +### ABAC cluster resources + +GitLab creates the following resources for ABAC clusters. -### Attribute-based access control (ABAC) +| Name | Type | Details | Created when | +|:------------------|:---------------------|:----------------------------------|:---------------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Deploying to a cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Deploying to a cluster | -| Name | Kind | Details | Created when | -| --- | --- | --- | --- | -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | -| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | +### RBAC cluster resources -### Role-based access control (RBAC) +GitLab creates the following resources for RBAC clusters. -| Name | Kind | Details | Created when | -| --- | --- | --- | --- | -| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | -| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | -| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | -| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | -| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | -| Project namespace | `ServiceAccount` | Uses namespace of Project | Creating/Adding a new GKE Cluster | -| Project namespace | `Secret` | Token for project ServiceAccount | Creating/Adding a new GKE Cluster | -| Project namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating/Adding a new GKE Cluster | +| Name | Type | Details | Created when | +|:------------------|:---------------------|:-----------------------------------------------------------------------------------------------------------|:---------------------------| +| `gitlab` | `ServiceAccount` | `default` namespace | Creating a new GKE Cluster | +| `gitlab-admin` | `ClusterRoleBinding` | [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Creating a new GKE Cluster | +| `gitlab-token` | `Secret` | Token for `gitlab` ServiceAccount | Creating a new GKE Cluster | +| `tiller` | `ServiceAccount` | `gitlab-managed-apps` namespace | Installing Helm Tiller | +| `tiller-admin` | `ClusterRoleBinding` | `cluster-admin` roleRef | Installing Helm Tiller | +| Project namespace | `ServiceAccount` | Uses namespace of Project | Deploying to a cluster | +| Project namespace | `Secret` | Token for project ServiceAccount | Deploying to a cluster | +| Project namespace | `RoleBinding` | [`edit`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) roleRef | Deploying to a cluster | + +NOTE: **Note:** +Project-specific resources are only created if your cluster is [managed by GitLab](#gitlab-managed-clusters). ### Security of GitLab Runners @@ -315,91 +347,38 @@ install it manually. ## Installing applications -NOTE: **Note:** -Before starting the installation of applications, make sure that time is synchronized -between your GitLab server and your Kubernetes cluster. Otherwise, installation could fail -and you may get errors like `Error: remote error: tls: bad certificate` -in the `stdout` of pods created by GitLab in your Kubernetes cluster. - -GitLab provides a one-click install for various applications which can -be added directly to your configured cluster. Those applications are -needed for [Review Apps](../../../ci/review_apps/index.md) and -[deployments](../../../ci/environments.md). You can install them after you -[create a cluster](#adding-and-creating-a-new-gke-cluster-via-gitlab). - -To see a list of available applications to install: - -1. Navigate to your project's **Operations > Kubernetes**. -1. Select your cluster. - -Install Helm Tiller first because it's used to install other applications. - -NOTE: **Note:** -As of GitLab 11.6, Helm Tiller will be upgraded to the latest version supported -by GitLab before installing any of the applications. - -| Application | GitLab version | Description | Helm Chart | -| ----------- | :------------: | ----------- | --------------- | -| [Helm Tiller](https://docs.helm.sh/) | 10.2+ | Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the `helm` CLI in a safe environment. | n/a | -| [Ingress](https://kubernetes.io/docs/concepts/services-networking/ingress/) | 10.2+ | Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications and is useful if you want to use [Auto DevOps] or deploy your own web apps. | [stable/nginx-ingress](https://github.com/helm/charts/tree/master/stable/nginx-ingress) | -| [Cert Manager](http://docs.cert-manager.io/en/latest/) | 11.6+ | Cert Manager is a native Kubernetes certificate management controller that helps with issuing certificates. Installing Cert Manager on your cluster will issue a certificate by [Let's Encrypt](https://letsencrypt.org/) and ensure that certificates are valid and up-to-date. | [stable/cert-manager](https://github.com/helm/charts/tree/master/stable/cert-manager) | -| [Prometheus](https://prometheus.io/docs/introduction/overview/) | 10.4+ | Prometheus is an open-source monitoring and alerting system useful to supervise your deployed applications. | [stable/prometheus](https://github.com/helm/charts/tree/master/stable/prometheus) | -| [GitLab Runner](https://docs.gitlab.com/runner/) | 10.6+ | GitLab Runner is the open source project that is used to run your jobs and send the results back to GitLab. It is used in conjunction with [GitLab CI/CD](https://about.gitlab.com/features/gitlab-ci-cd/), the open-source continuous integration service included with GitLab that coordinates the jobs. When installing the GitLab Runner via the applications, it will run in **privileged mode** by default. Make sure you read the [security implications](#security-implications) before doing so. | [runner/gitlab-runner](https://gitlab.com/charts/gitlab-runner) | -| [JupyterHub](http://jupyter.org/) | 11.0+ | [JupyterHub](https://jupyterhub.readthedocs.io/en/stable/) is a multi-user service for managing notebooks across a team. [Jupyter Notebooks](https://jupyter-notebook.readthedocs.io/en/latest/) provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. We use a [custom Jupyter image](https://gitlab.com/gitlab-org/jupyterhub-user-image/blob/master/Dockerfile) that installs additional useful packages on top of the base Jupyter. You will also see ready-to-use DevOps Runbooks built with Nurtch's [Rubix library](https://github.com/amit1rrr/rubix). More information on creating executable runbooks can be found in [our Nurtch documentation](runbooks/index.md#nurtch-executable-runbooks). **Note**: Authentication will be enabled for any user of the GitLab server via OAuth2. HTTPS will be supported in a future release. | [jupyter/jupyterhub](https://jupyterhub.github.io/helm-chart/) | -| [Knative](https://cloud.google.com/knative) | 11.5+ | Knative provides a platform to create, deploy, and manage serverless workloads from a Kubernetes cluster. It is used in conjunction with, and includes [Istio](https://istio.io) to provide an external IP address for all programs hosted by Knative. You will be prompted to enter a wildcard domain where your applications will be exposed. Configure your DNS server to use the external IP address for that domain. For any application created and installed, they will be accessible as `<program_name>.<kubernetes_namespace>.<domain_name>`. This will require your kubernetes cluster to have [RBAC enabled](#role-based-access-control-rbac). | [knative/knative](https://storage.googleapis.com/triggermesh-charts) - -With the exception of Knative, the applications will be installed in a dedicated -namespace called `gitlab-managed-apps`. - -CAUTION: **Caution:** -If you have an existing Kubernetes cluster with Tiller already installed, -you should be careful as GitLab cannot detect it. In this case, installing -Tiller via the applications will result in the cluster having it twice, which -can lead to confusion during deployments. - -### Upgrading applications - -> [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/24789) -in GitLab 11.8. - -Users can perform a one-click upgrade for the GitLab Runner application, -when there is an upgrade available. - -To upgrade the GitLab Runner application: - -1. Navigate to your project's **Operations > Kubernetes**. -1. Select your cluster. -1. Click the **Upgrade** button for the Runnner application. - -The **Upgrade** button will not be shown if there is no upgrade -available. +GitLab can install and manage some applications in your project-level +cluster. For more information on installing, upgrading, uninstalling, +and troubleshooting applications for your project cluster, see +[Gitlab Managed Apps](../../clusters/applications.md). -NOTE: **Note:** -Upgrades will reset values back to the values built into the `runner` -chart plus the values set by -[`values.yaml`](https://gitlab.com/gitlab-org/gitlab-ce/blob/master/vendor/runner/values.yaml) - -## Getting the external IP address +## Getting the external endpoint NOTE: **Note:** With the following procedure, a load balancer must be installed in your cluster -to obtain the external IP address. You can use either +to obtain the endpoint. You can use either [Ingress](#installing-applications), or Knative's own load balancer ([Istio](https://istio.io)) if using [Knative](#installing-applications). -In order to publish your web application, you first need to find the external IP -address associated to your load balancer. +In order to publish your web application, you first need to find the endpoint which will be either an IP +address or a hostname associated with your load balancer. -### Let GitLab fetch the IP address +### Automatically determining the external endpoint > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/merge_requests/17052) in GitLab 10.6. -If you [installed Ingress or Knative](#installing-applications), -you should see the Ingress IP address on this same page within a few minutes. -If you don't see this, GitLab might not be able to determine the IP address of -your ingress application in which case you should manually determine it. +After you install [Ingress or Knative](#installing-applications), Gitlab attempts to determine the external endpoint +and it should be available within a few minutes. If the endpoint doesn't appear +and your cluster runs on Google Kubernetes Engine: + +1. Check your [Kubernetes cluster on Google Kubernetes Engine](https://console.cloud.google.com/kubernetes) to ensure there are no errors on its nodes. +1. Ensure you have enough [Quotas](https://console.cloud.google.com/iam-admin/quotas) on Google Kubernetes Engine. For more information, see [Resource Quotas](https://cloud.google.com/compute/quotas). +1. Check [Google Cloud's Status](https://status.cloud.google.com/) to ensure they are not having any disruptions. -### Manually determining the IP address +If GitLab is still unable to determine the endpoint of your Ingress or Knative application, you can +manually determine it by following the steps below. + +### Manually determining the external endpoint If the cluster is on GKE, click the **Google Kubernetes Engine** link in the **Advanced settings**, or go directly to the @@ -409,7 +388,7 @@ the `gcloud` command in a local terminal or using the **Cloud Shell**. If the cluster is not on GKE, follow the specific instructions for your Kubernetes provider to configure `kubectl` with the right credentials. -The output of the following examples will show the external IP address of your +The output of the following examples will show the external endpoint of your cluster. This information can then be used to set up DNS entries and forwarding rules that allow external access to your deployed applications. @@ -417,19 +396,19 @@ If you installed the Ingress [via the **Applications**](#installing-applications run the following command: ```bash -kubectl get svc --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' +kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].ip}' ``` -For Istio/Knative, the command will be different: +Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: ```bash -kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' +kubectl get service --namespace=gitlab-managed-apps ingress-nginx-ingress-controller -o jsonpath='{.status.loadBalancer.ingress[0].hostname}' ``` -Some Kubernetes clusters return a hostname instead, like [Amazon EKS](https://aws.amazon.com/eks/). For these platforms, run: +For Istio/Knative, the command will be different: ```bash -kubectl get service ingress-nginx-ingress-controller -n gitlab-managed-apps -o jsonpath="{.status.loadBalancer.ingress[0].hostname}". +kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' ``` Otherwise, you can list the IP addresses of all load balancers: @@ -448,13 +427,12 @@ reserved IP. Read how to [promote an ephemeral external IP address in GKE](https://cloud.google.com/compute/docs/ip-addresses/reserve-static-external-ip-address#promote_ephemeral_ip). -### Pointing your DNS at the cluster IP +### Pointing your DNS at the external endpoint -Once you've set up the static IP, you should associate it to a [wildcard DNS -record](https://en.wikipedia.org/wiki/Wildcard_DNS_record), in order to be able -to reach your apps. This heavily depends on your domain provider, but in case -you aren't sure, just create an A record with a wildcard host like -`*.example.com.`. +Once you've set up the external endpoint, you should associate it with a [wildcard DNS +record](https://en.wikipedia.org/wiki/Wildcard_DNS_record) such as `*.example.com.` +in order to be able to reach your apps. If your external endpoint is an IP address, +use an A record. If your external endpoint is a hostname, use a CNAME record. ## Multiple Kubernetes clusters **[PREMIUM]** @@ -465,17 +443,14 @@ project. That way you can have different clusters for different environments, like dev, staging, production, etc. Simply add another cluster, like you did the first time, and make sure to -[set an environment scope](#setting-the-environment-scope) that will +[set an environment scope](#setting-the-environment-scope-premium) that will differentiate the new cluster with the rest. ## Setting the environment scope **[PREMIUM]** -When adding more than one Kubernetes clusters to your project, you need -to differentiate them with an environment scope. The environment scope -associates clusters with [environments](../../../ci/environments.md) -similar to how the [environment-specific -variables](../../../ci/variables/README.md#limiting-environment-scopes-of-variables) -work. +When adding more than one Kubernetes cluster to your project, you need to differentiate +them with an environment scope. The environment scope associates clusters with [environments](../../../ci/environments.md) similar to how the +[environment-specific variables](../../../ci/variables/README.md#limiting-environment-scopes-of-environment-variables-premium) work. The default environment scope is `*`, which means all jobs, regardless of their environment, will use that cluster. Each scope can only be used by a single @@ -527,7 +502,7 @@ The result will then be: ## Deployment variables The Kubernetes cluster integration exposes the following -[deployment variables](../../../ci/variables/README.md#deployment-variables) in the +[deployment variables](../../../ci/variables/README.md#deployment-environment-variables) in the GitLab CI/CD build environment. | Variable | Description | @@ -538,33 +513,34 @@ GitLab CI/CD build environment. | `KUBE_CA_PEM_FILE` | Path to a file containing PEM data. Only present if a custom CA bundle was specified. | | `KUBE_CA_PEM` | (**deprecated**) Raw PEM data. Only if a custom CA bundle was specified. | | `KUBECONFIG` | Path to a file containing `kubeconfig` for this deployment. CA bundle would be embedded if specified. This config also embeds the same token defined in `KUBE_TOKEN` so you likely will only need this variable. This variable name is also automatically picked up by `kubectl` so you won't actually need to reference it explicitly if using `kubectl`. | -| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | +| `KUBE_INGRESS_BASE_DOMAIN` | From GitLab 11.8, this variable can be used to set a domain per cluster. See [cluster domains](#base-domain) for more information. | NOTE: **NOTE:** Prior to GitLab 11.5, `KUBE_TOKEN` was the Kubernetes token of the main service account of the cluster integration. -### Troubleshooting missing `KUBECONFIG` or `KUBE_TOKEN` +### Troubleshooting failed deployment jobs + +GitLab will create a namespace and service account specifically for your +deployment jobs. On project level clusters, this happens when the cluster +is created. On group level clusters, resources are created immediately +before the deployment job starts. -GitLab will create a new service account specifically for your CI builds. The -new service account is created when the cluster is added to the project. -Sometimes there may be errors that cause the service account creation to fail. +However, sometimes GitLab can not create them. In such instances, your job will fail with the message: -In such instances, your build will not be passed the `KUBECONFIG` or -`KUBE_TOKEN` variables and, if you are using Auto DevOps, your Auto DevOps -pipelines will no longer trigger a `production` deploy build. You will need to -check the [logs](../../../administration/logs.md) to debug why the service -account creation failed. +```text +This job failed because the necessary resources were not successfully created. +``` -A common reason for failure is that the token you gave GitLab did not have -[`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) -privileges as GitLab expects. +To find the cause of this error when creating a namespace and service account, check the [logs](../../../administration/logs.md#kuberneteslog). -Another common problem for why these variables are not being passed to your -builds is that they must have a matching -[`environment:name`](../../../ci/environments.md#defining-environments). If -your build has no `environment:name` set, it will not be passed the Kubernetes -credentials. +Common reasons for failure include: + +- The token you gave GitLab did not have [`cluster-admin`](https://kubernetes.io/docs/reference/access-authn-authz/rbac/#user-facing-roles) + privileges required by GitLab. +- Missing `KUBECONFIG` or `KUBE_TOKEN` variables. To be passed to your job, they must have a matching + [`environment:name`](../../../ci/environments.md#defining-environments). If your job has no + `environment:name` set, it will not be passed the Kubernetes credentials. ## Monitoring your Kubernetes cluster **[ULTIMATE]** @@ -572,7 +548,7 @@ credentials. When [Prometheus is deployed](#installing-applications), GitLab will automatically monitor the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start. - + ## Enabling or disabling the Kubernetes cluster integration @@ -600,11 +576,6 @@ To remove the Kubernetes cluster integration from your project, simply click the **Remove integration** button. You will then be able to follow the procedure and add a Kubernetes cluster again. -## View Kubernetes pod logs from GitLab **[ULTIMATE]** - -Learn how to easily -[view the logs of running pods in connected Kubernetes clusters](https://docs.gitlab.com/ee/user/project/clusters/kubernetes_pod_logs.html). - ## What you can get with the Kubernetes integration Here's what you can do with GitLab if you enable the Kubernetes integration. @@ -617,7 +588,7 @@ displaying the status of the pods in the deployment. Developers and other teammates can view the progress and status of a rollout, pod by pod, in the workflow they already use without any need to access Kubernetes. -[Read more about Deploy Boards](https://docs.gitlab.com/ee/user/project/deploy_boards.html) +[Read more about Deploy Boards](../deploy_boards.md) ### Canary Deployments **[PREMIUM]** @@ -625,7 +596,13 @@ Leverage [Kubernetes' Canary deployments](https://kubernetes.io/docs/concepts/cl and visualize your canary deployments right inside the Deploy Board, without the need to leave GitLab. -[Read more about Canary Deployments](https://docs.gitlab.com/ee/user/project/canary_deployments.html) +[Read more about Canary Deployments](../canary_deployments.md) + +### Pod logs **[ULTIMATE]** + +GitLab makes it easy to view the logs of running pods in connected Kubernetes clusters. By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. + +[Read more about Kubernetes pod logs](kubernetes_pod_logs.md) ### Kubernetes monitoring diff --git a/doc/user/project/clusters/kubernetes_pod_logs.md b/doc/user/project/clusters/kubernetes_pod_logs.md new file mode 100644 index 00000000000..368031070c1 --- /dev/null +++ b/doc/user/project/clusters/kubernetes_pod_logs.md @@ -0,0 +1,21 @@ +# Kubernetes Pod Logs **[ULTIMATE]** + +> [Introduced](https://gitlab.com/gitlab-org/gitlab-ee/issues/4752) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 11.0. + +GitLab makes it easy to view the logs of running pods in [connected Kubernetes clusters](index.md). +By displaying the logs directly in GitLab, developers can avoid having to manage console tools or jump to a different interface. + +## Overview + +[Kubernetes](https://kubernetes.io) pod logs can be viewed directly within GitLab. Logs can be displayed by clicking on a specific pod from [Deploy Boards](../deploy_boards.md): + +1. Go to **Operations > Environments** and find the environment which contains the desired pod, like `production`. +1. On the **Environments** page, you should see the status of the environment's pods with [Deploy Boards](../deploy_boards.md). +1. When mousing over the list of pods, a tooltip will appear with the exact pod name and status. + +1. Click on the desired pod to bring up the logs view, which will contain the last 500 lines for that pod. Support for pods with multiple containers is coming [in a future release](https://gitlab.com/gitlab-org/gitlab-ee/issues/6502). + + +## Requirements + +[Enabling Deploy Boards](../deploy_boards.md#enabling-deploy-boards) is required in order to be able to use Pod Logs. diff --git a/doc/user/project/clusters/runbooks/img/authorize-jupyter.png b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png Binary files differindex 84cce311483..f3e868de802 100644 --- a/doc/user/project/clusters/runbooks/img/authorize-jupyter.png +++ b/doc/user/project/clusters/runbooks/img/authorize-jupyter.png diff --git a/doc/user/project/clusters/runbooks/img/gitlab-variables.png b/doc/user/project/clusters/runbooks/img/gitlab-variables.png Binary files differindex 1d338f063a9..7c9c9099851 100644 --- a/doc/user/project/clusters/runbooks/img/gitlab-variables.png +++ b/doc/user/project/clusters/runbooks/img/gitlab-variables.png diff --git a/doc/user/project/clusters/runbooks/img/helm-install.png b/doc/user/project/clusters/runbooks/img/helm-install.png Binary files differindex 003e482e756..e67cf317ec1 100644 --- a/doc/user/project/clusters/runbooks/img/helm-install.png +++ b/doc/user/project/clusters/runbooks/img/helm-install.png diff --git a/doc/user/project/clusters/runbooks/img/ingress-install.png b/doc/user/project/clusters/runbooks/img/ingress-install.png Binary files differindex 7edc11d5b45..08256a65138 100644 --- a/doc/user/project/clusters/runbooks/img/ingress-install.png +++ b/doc/user/project/clusters/runbooks/img/ingress-install.png diff --git a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png Binary files differindex 75c6028a763..784e508ff25 100644 --- a/doc/user/project/clusters/runbooks/img/jupyterhub-install.png +++ b/doc/user/project/clusters/runbooks/img/jupyterhub-install.png diff --git a/doc/user/project/clusters/runbooks/img/postgres-query.png b/doc/user/project/clusters/runbooks/img/postgres-query.png Binary files differindex 04315d54d5e..dbb5a62ebba 100644 --- a/doc/user/project/clusters/runbooks/img/postgres-query.png +++ b/doc/user/project/clusters/runbooks/img/postgres-query.png diff --git a/doc/user/project/clusters/runbooks/img/sample-runbook.png b/doc/user/project/clusters/runbooks/img/sample-runbook.png Binary files differindex 70011202bf0..545d34fd4ad 100644 --- a/doc/user/project/clusters/runbooks/img/sample-runbook.png +++ b/doc/user/project/clusters/runbooks/img/sample-runbook.png diff --git a/doc/user/project/clusters/runbooks/index.md b/doc/user/project/clusters/runbooks/index.md index 512a4cb32f4..c67b12fb91a 100644 --- a/doc/user/project/clusters/runbooks/index.md +++ b/doc/user/project/clusters/runbooks/index.md @@ -4,6 +4,10 @@ Runbooks are a collection of documented procedures that explain how to carry out a particular process, be it starting, stopping, debugging, or troubleshooting a particular system. +Using [Jupyter Notebooks](https://jupyter.org/) and the [Rubix library](https://github.com/Nurtch/rubix), +users can get started writing their own executable runbooks. + + ## Overview Historically, runbooks took the form of a decision tree or a detailed @@ -13,13 +17,15 @@ Modern implementations have introduced the concept of an "executable runbooks", where, along with a well-defined process, operators can execute pre-written code blocks or database queries against a given environment. -## Nurtch Executable Runbooks +## Executable Runbooks > [Introduced](https://gitlab.com/gitlab-org/gitlab-ce/issues/45912) in GitLab 11.4. The JupyterHub app offered via GitLab’s Kubernetes integration now ships with Nurtch’s Rubix library, providing a simple way to create DevOps -runbooks. A sample runbook is provided, showcasing common operations. +runbooks. A sample runbook is provided, showcasing common operations. While Rubix makes it +simple to create common Kubernetes and AWS workflows, you can also create them manually without +Rubix. **<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch this [video](https://www.youtube.com/watch?v=Q_OqHIIUPjE) @@ -30,13 +36,13 @@ for an overview of how this is accomplished in GitLab!** To create an executable runbook, you will need: 1. **Kubernetes** - A Kubernetes cluster is required to deploy the rest of the applications. - The simplest way to get started is to add a cluster using [GitLab's GKE integration](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab). + The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). 1. **Helm Tiller** - Helm is a package manager for Kubernetes and is required to install all the other applications. It is installed in its own pod inside the cluster which can run the helm CLI in a safe environment. 1. **Ingress** - Ingress can provide load balancing, SSL termination, and name-based virtual hosting. It acts as a web proxy for your applications. -1. **JupyterHub** - JupyterHub is a multi-user service for managing notebooks across +1. **JupyterHub** - [JupyterHub](https://jupyterhub.readthedocs.io/) is a multi-user service for managing notebooks across a team. Jupyter Notebooks provide a web-based interactive programming environment used for data analysis, visualization, and machine learning. @@ -55,7 +61,7 @@ the components outlined above and the preloaded demo runbook. ### 1. Add a Kubernetes cluster -Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](https://docs.gitlab.com/ee/user/project/clusters/#adding-and-creating-a-new-gke-cluster-via-gitlab) +Follow the steps outlined in [Adding and creating a new GKE cluster via GitLab](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab) to add a Kubernetes cluster to your project. ### 2. Install Helm Tiller, Ingress, and JupyterHub @@ -86,7 +92,7 @@ The server will take a couple of seconds to start. ### 4. Configure access In order for the runbook to access your GitLab project, you will need to enter a -[GitLab Access Token](https://docs.gitlab.com/ee/user/profile/personal_access_tokens.html) +[GitLab Access Token](../../../profile/personal_access_tokens.md) as well as your Project ID in the **Setup** section of the demo runbook. Double-click the **DevOps-Runbook-Demo** folder located on the left panel. diff --git a/doc/user/project/clusters/serverless/img/function-details-loaded.png b/doc/user/project/clusters/serverless/img/function-details-loaded.png Binary files differnew file mode 100644 index 00000000000..34465c5c087 --- /dev/null +++ b/doc/user/project/clusters/serverless/img/function-details-loaded.png diff --git a/doc/user/project/clusters/serverless/index.md b/doc/user/project/clusters/serverless/index.md index 46d50f8894a..2cda850f24e 100644 --- a/doc/user/project/clusters/serverless/index.md +++ b/doc/user/project/clusters/serverless/index.md @@ -11,18 +11,22 @@ Run serverless workloads on Kubernetes using [Knative](https://cloud.google.com/ Knative extends Kubernetes to provide a set of middleware components that are useful to build modern, source-centric, container-based applications. Knative brings some significant benefits out of the box through its main components: -- [Build](https://github.com/knative/build): Source-to-container build orchestration. -- [Eventing](https://github.com/knative/eventing): Management and delivery of events. - [Serving](https://github.com/knative/serving): Request-driven compute that can scale to zero. +- [Eventing](https://github.com/knative/eventing): Management and delivery of events. For more information on Knative, visit the [Knative docs repo](https://github.com/knative/docs). -With GitLab serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. +With GitLab Serverless, you can deploy both functions-as-a-service (FaaS) and serverless applications. -## Requirements +## Prerequisites To run Knative on Gitlab, you will need: +1. **Existing GitLab project:** You will need a GitLab project to associate all resources. The simplest way to get started: + + - If you are planning on deploying functions, clone the [functions example project](https://gitlab.com/knative-examples/functions) to get started. + - If you are planning on deploying a serverless application, clone the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. + 1. **Kubernetes Cluster:** An RBAC-enabled Kubernetes cluster is required to deploy Knative. The simplest way to get started is to add a cluster using [GitLab's GKE integration](../index.md#adding-and-creating-a-new-gke-cluster-via-gitlab). The set of minimum recommended cluster specifications to run Knative is 3 nodes, 6 vCPUs, and 22.50 GB memory. @@ -32,17 +36,22 @@ To run Knative on Gitlab, you will need: applications or functions onto your cluster. You can install the GitLab Runner onto the existing Kubernetes cluster. See [Installing Applications](../index.md#installing-applications) for more information. 1. **Domain Name:** Knative will provide its own load balancer using Istio. It will provide an - external IP address for all the applications served by Knative. You will be prompted to enter a + external IP address or hostname for all the applications served by Knative. You will be prompted to enter a wildcard domain where your applications will be served. Configure your DNS server to use the - external IP address for that domain. + external IP address or hostname for that domain. 1. **`.gitlab-ci.yml`:** GitLab uses [Kaniko](https://github.com/GoogleContainerTools/kaniko) - to build the application and the [TriggerMesh CLI](https://github.com/triggermesh/tm) to simplify the - deployment of knative services and functions. + to build the application. We also use [gitlabktl](https://gitlab.com/gitlab-org/gitlabktl) + and [TriggerMesh CLI](https://github.com/triggermesh/tm) CLIs to simplify the + deployment of services and functions to Knative. 1. **`serverless.yml`** (for [functions only](#deploying-functions)): When using serverless to deploy functions, the `serverless.yml` file will contain the information for all the functions being hosted in the repository as well as a reference to the runtime being used. -1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a `Dockerfile` in order to build your application. It should be included - at the root of your project's repo and expose port `8080`. +1. **`Dockerfile`** (for [applications only](#deploying-serverless-applications): Knative requires a + `Dockerfile` in order to build your applications. It should be included at the root of your + project's repo and expose port `8080`. `Dockerfile` is not require if you plan to build serverless functions + using our [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes). +1. **Prometheus** (optional): Installing Prometheus allows you to monitor the scale and traffic of your serverless function/application. + See [Installing Applications](../index.md#installing-applications) for more information. ## Installing Knative via GitLab's Kubernetes integration @@ -55,23 +64,18 @@ The minimum recommended cluster size to run Knative is 3-nodes, 6 vCPUs, and 22.  -1. After the Knative installation has finished, you can wait for the IP address to be displayed in the - **Knative IP Address** field or retrieve the Istio Ingress IP address by running the following command: - - ```bash - kubectl get svc --namespace=istio-system knative-ingressgateway -o jsonpath='{.status.loadBalancer.ingress[0].ip} ' - ``` - - Output: +1. After the Knative installation has finished, you can wait for the IP address or hostname to be displayed in the + **Knative Endpoint** field or [retrieve the Istio Ingress Endpoint manually](../#manually-determining-the-external-endpoint). - ```bash - 35.161.143.124 my-machine-name:~ my-user$ - ``` + NOTE: **Note:** + Running `kubectl` commands on your cluster requires setting up access to the cluster first. + For clusters created on GKE, see [GKE Cluster Access](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl), + for other platforms [Install kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). 1. The ingress is now available at this address and will route incoming requests to the proper service based on the DNS name in the request. To support this, a wildcard DNS A record should be created for the desired domain name. For example, - if your Knative base domain is `example.com` then you need to create an A record with domain `*.example.com` - pointing the ip address of the ingress. + if your Knative base domain is `knative.info` then you need to create an A record or CNAME record with domain `*.knative.info` + pointing the ip address or hostname of the ingress.  @@ -87,14 +91,15 @@ Using functions is useful for dealing with independent events without needing to maintain a complex unified infrastructure. This allows you to focus on a single task that can be executed/scaled automatically and independently. -Currently the following [runtimes](https://gitlab.com/triggermesh/runtimes) are offered: +Currently the following [runtimes](https://gitlab.com/gitlab-org/serverless/runtimes) are offered: +- ruby - node.js -- kaniko +- Dockerfile You can find and import all the files referenced in this doc in the **[functions example project](https://gitlab.com/knative-examples/functions)**. -Follow these steps to deploy a function using the Node.js runtime to your Knative instance: +Follow these steps to deploy a function using the Node.js runtime to your Knative instance (you can skip these steps if you've cloned the example project): 1. Create a directory that will house the function. In this example we will create a directory called `echo` at the root of the project. @@ -102,53 +107,60 @@ Follow these steps to deploy a function using the Node.js runtime to your Knativ - Public, continue to the next step. - Private, you will need to [create a GitLab deploy token](../../deploy_tokens/index.md#creating-a-deploy-token) with `gitlab-deploy-token` as the name and the `read_registry` scope. -1. `.gitlab-ci.yml`: This template allows to define the stage, environment, and - image to be used for your functions. It must be included at the root of your repository: +1. `.gitlab-ci.yml`: this defines a pipeline used to deploy your functions. + It must be included at the root of your repository: ```yaml - stages: - - deploy + include: + template: Serverless.gitlab-ci.yml - functions: - stage: deploy - environment: test - image: gcr.io/triggermesh/tm:v0.0.9 - script: - - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_REGISTRY_USER" --password "$CI_JOB_TOKEN" --push - - tm -n "$KUBE_NAMESPACE" set registry-auth gitlab-registry --registry "$CI_REGISTRY" --username "$CI_DEPLOY_USER" --password "$CI_DEPLOY_PASSWORD" --pull - - tm -n "$KUBE_NAMESPACE" deploy --wait + functions:build: + extends: .serverless:build:functions + environment: production + functions:deploy: + extends: .serverless:deploy:functions + environment: production ``` - The `gitlab-ci.yml` template creates a `Deploy` stage with a `functions` job that invokes the `tm` CLI with the required parameters. + This `.gitlab-ci.yml` creates jobs that invoke some predefined commands to + build and deploy your functions to your cluster. + + `Serverless.gitlab-ci.yml` is a template that allows customization. + You can either import it with `include` parameter and use `extends` to + customize your jobs, or you can inline the entire template by choosing it + from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through + the user interface. -2. `serverless.yml`: This file contains the metadata for your functions, - such as name, runtime, and environment. It must be included at the root of your repository. The following is a sample `echo` function which shows the required structure for the file. You can find the relevant files for this project in the [functions example project](https://gitlab.com/knative-examples/functions). +2. `serverless.yml`: this file contains the metadata for your functions, + such as name, runtime, and environment. + + It must be included at the root of your repository. + The following is a sample `echo` function which shows the required structure + for the file. + + You can find the relevant files for this project in the [functions example project](https://gitlab.com/knative-examples/functions). ```yaml - service: my-functions - description: "Deploying functions from GitLab using Knative" + service: functions + description: "GitLab Serverless functions using Knative" provider: name: triggermesh - registry-secret: gitlab-registry environment: - FOO: BAR + FOO: value functions: - echo: - handler: echo - runtime: https://gitlab.com/triggermesh/runtimes/raw/master/nodejs.yaml - description: "echo function using node.js runtime" - buildargs: - - DIRECTORY=echo + echo-js: + handler: echo-js + source: ./echo-js + runtime: https://gitlab.com/gitlab-org/serverless/runtimes/nodejs + description: "node.js runtime function" environment: - FUNCTION: echo + MY_FUNCTION: echo-js ``` -The `serverless.yml` file references both an `echo` directory (under `buildargs`) and an `echo` file (under `handler`), -which is a reference to `echo.js` in the [repository](https://gitlab.com/knative-examples/functions). Additionally, it -contains three sections with distinct parameters: +Explanation of the fields used above: ### `service` @@ -162,7 +174,6 @@ contains three sections with distinct parameters: | Parameter | Description | |-----------|-------------| | `name` | Indicates which provider is used to execute the `serverless.yml` file. In this case, the TriggerMesh `tm` CLI. | -| `registry-secret` | Indicates which registry will be used to store docker images. The sample function is using the GitLab Registry (`gitlab-registry`). A different registry host may be specified using `registry` key in the `provider` object. If changing the default, update the permission and the secret value on the `gitlab-ci.yml` file | | `environment` | Includes the environment variables to be passed as part of function execution for **all** functions in the file, where `FOO` is the variable name and `BAR` are he variable contents. You may replace this with you own variables. | ### `functions` @@ -171,10 +182,10 @@ In the `serverless.yml` example above, the function name is `echo` and the subse | Parameter | Description | |-----------|-------------| -| `handler` | The function's file name. In the example above, both the function name and the handler are the same. | +| `handler` | The function's name. | +| `source` | Directory with sources of a functions. | | `runtime` | The runtime to be used to execute the function. | | `description` | A short description of the function. | -| `buildargs` | Pointer to the function file in the repo. In the sample the function is located in the `echo` directory. | | `environment` | Sets an environment variable for the specific function only. | After the `gitlab-ci.yml` template has been added and the `serverless.yml` file has been @@ -188,7 +199,7 @@ appear under **Operations > Serverless**. This page contains all functions available for the project, the description for accessing the function, and, if available, the function's runtime information. The details are derived from the Knative installation inside each of the project's -Kubernetes cluster. +Kubernetes cluster. Click on each function to obtain detailed scale and invocation data. The function details can be retrieved directly from Knative on the cluster: @@ -198,7 +209,7 @@ kubectl -n "$KUBE_NAMESPACE" get services.serving.knative.dev The sample function can now be triggered from any HTTP client using a simple `POST` call: - 1. Using curl + 1. Using curl (replace the URL on the last line with the URL of your application): ```bash curl \ @@ -219,35 +230,25 @@ NOTE: **Note:** You can reference and import the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) to get started. Add the following `.gitlab-ci.yml` to the root of your repository -(you may skip this step if using the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above): +(you may skip this step if you've previously cloned the sample [Knative Ruby App](https://gitlab.com/knative-examples/knative-ruby-app) mentioned above): ```yaml -stages: - - build - - deploy +include: + template: Serverless.gitlab-ci.yml build: - stage: build - image: - name: gcr.io/kaniko-project/executor:debug - entrypoint: [""] - only: - - master - script: - - echo "{\"auths\":{\"$CI_REGISTRY\":{\"username\":\"$CI_REGISTRY_USER\",\"password\":\"$CI_REGISTRY_PASSWORD\"}}}" > /kaniko/.docker/config.json - - /kaniko/executor --context $CI_PROJECT_DIR --dockerfile $CI_PROJECT_DIR/Dockerfile --destination $CI_REGISTRY_IMAGE + extends: .serverless:build:image deploy: - stage: deploy - image: gcr.io/triggermesh/tm@sha256:e3ee74db94d215bd297738d93577481f3e4db38013326c90d57f873df7ab41d5 - only: - - master - environment: production - script: - - echo "$CI_REGISTRY_IMAGE" - - tm -n "$KUBE_NAMESPACE" --config "$KUBECONFIG" deploy service "$CI_PROJECT_NAME" --from-image "$CI_REGISTRY_IMAGE" --wait + extends: .serverless:deploy:image ``` +`Serverless.gitlab-ci.yml` is a template that allows customization. +You can either import it with `include` parameter and use `extends` to +customize your jobs, or you can inline the entire template by choosing it +from **Apply a template** dropdown when editing the `.gitlab-ci.yml` file through +the user interface. + ### Deploy the application with Knative With all the pieces in place, the next time a CI pipeline runs, the Knative application will be deployed. Navigate to @@ -285,3 +286,23 @@ The second to last line, labeled **Service domain** contains the URL for the dep browser to see the app live.  + +## Function details + +Go to the **Operations > Serverless** page and click on one of the function +rows to bring up the function details page. + + + +The pod count will give you the number of pods running the serverless function instances on a given cluster. + +### Prometheus support + +For the Knative function invocations to appear, +[Prometheus must be installed](../index.md#installing-applications). + +Once Prometheus is installed, a message may appear indicating that the metrics data _is +loading or is not available at this time._ It will appear upon the first access of the +page, but should go away after a few seconds. If the message does not disappear, then it +is possible that GitLab is unable to connect to the Prometheus instance running on the +cluster. |
