Untitled
unknown
plain_text
2 years ago
31 kB
5
Indexable
# Create a Kubernetes Cluster With the AWS EKS CLI (eksctl)
[[_TOC_]]
## Install AWS CLI version
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="948" height="65" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-283.png" alt="Checking the AWS CLI version" class="wp-image-12868" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-283.png 948w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-283-300x21.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-283-768x53.png 768w" sizes="(max-width: 948px) 100vw, 948px" /><figcaption> Checking the AWS CLI version </figcaption></figure></div>
<p> Run <code>curl</code> command below to download the CLI tool v2+ and save it in a zip file named <code>awscliv2.zip</code>. </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1214" height="113" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-284.png" alt="Downloading the CLI tool v2+" class="wp-image-12869" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-284.png 1214w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-284-300x28.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-284-1024x95.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-284-768x71.png 768w" sizes="(max-width: 1214px) 100vw, 1214px" /><figcaption> Downloading the CLI tool v2+ </figcaption></figure></div>
<p> Run the following commands to unzip the downloaded file and determine where the outdated AWS CLI is installed.</p>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">unzip awscliv2.zip
which aws</code></pre>
</div>
<p>As you can see from the output below, the outdated AWS CLI is installed at <strong>/usr/bin/aws</strong>. You need to update this path with the updated version. </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="433" height="82" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-285.png" alt="Updating outdated AWS CLI" class="wp-image-12870" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-285.png 433w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-285-300x57.png 300w" sizes="(max-width: 433px) 100vw, 433px" /><figcaption>Updating outdated AWS CLI</figcaption></figure></div>
<p> Run the command below to perform the following and –update the AWS CLI’s install path on your instance:</p>
<ul><li>Install the updated AWS CLI tools on your Amazon Linux 2 instance (<code>sudo ./aws/install</code>).</li><li>Set the directory (<code>--install-dir /usr/bin/aws-cli</code>) where to install the CLI tools. Doing so lets you transfer the updated AWS CLI to other instances without reinstalling the CLI tools.</li><li>Update (<code>--update</code>) your current shell environment with the new path for AWS CLI tools if there’s one in your current environment.</li></ul>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">sudo ./aws/install --bin-dir /usr/bin --install-dir /usr/bin/aws-cli --update</code></pre>
</div>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1165" height="82" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-286.png" alt="Installing the CLI tool v2" class="wp-image-12871" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-286.png 1165w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-286-300x21.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-286-1024x72.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-286-768x54.png 768w" sizes="(max-width: 1165px) 100vw, 1165px" /><figcaption> Installing the CLI tool v2 </figcaption></figure></div>
<p> Rerun the <code>aws --version</code> command below to check that the updated AWS CLI is installed correctly. </p>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">aws --version</code></pre>
</div>
<p>The AWS CLI version installed is <strong>2.4.7</strong>, as shown below, which is the latest AWS CLI version is 2.4.7 at the time of writing. </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1253" height="59" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-287.png" alt="Checking the AWS CLI updated version" class="wp-image-12872" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-287.png 1253w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-287-300x14.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-287-1024x48.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-287-768x36.png 768w" sizes="(max-width: 1253px) 100vw, 1253px" /><figcaption> Checking the AWS CLI updated version </figcaption></figure></div>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash"> curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o "awscliv2.zip" </code></pre>
</div>
## Install Amazon EKS Command-Line Tool (eksctl) and Kubernetes command-line tool (kubectl)
<p>Since your goal is to create a Kubernetes cluster with AWS EKS CLI, you’ll also configure <a href="https://docs.aws.amazon.com/eks/latest/userguide/getting-started-eksctl.html" target="_blank" rel="noreferrer noopener nofollow">Amazon EKS (eksctl)</a> command-line tool. This tool lets you create and manage Kubernetes clusters on Amazon EKS.</p>
<p><a href="https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html" target="_blank" rel="noreferrer noopener">1. Install the latest version</a> of the Kubernetes command-line tool (<a href="https://kubernetes.io/docs/reference/kubectl/kubectl/" target="_blank" rel="noreferrer noopener nofollow">kubectl</a>) This tool allows you to run commands against Kubernetes clusters.</p>
<p>2. Next, run the <code>curl</code> command below to retrieve the latest <code>eksctl</code> release from GitHub to your <em>/tmp</em> directory as a <em>.tar.gz</em> file, then extract the archive content into the /tmp directory. </p>
<p>Run the below commands to perform the following:</p>
<ul><li>Retrieve the latest <code>eksctl</code> release from GitHub (<code>--location</code>) as <em>.tar.gz</em> archive (<code>"<https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$>(uname -s)_amd64.tar.gz"</code>)</li><li>Extract the archive’s content to the <em>/tmp</em> directory (<code>tar xz -C /tmp</code>), while the <code>--silent</code> flag suppresses the command’s progress output.</li><li>Move (<code>sudo mv</code>) the eksctl binary (<code>/tmp/eksctl</code>) to the path where you installed the AWS CLI (<code>/usr/bin</code>)</li></ul>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">curl --silent --location "https://github.com/weaveworks/eksctl/releases/latest/download/eksctl_$(uname -s)_amd64.tar.gz" | tar xz -C /tmp
sudo mv /tmp/eksctl /usr/bin</code></pre>
</div>
<p>3. Finally, run the command below to confirm you’ve successfully installed <code>eksctl</code>. </p>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">eksctl version</code></pre>
</div>
<p>The output below confirms that you’ve installed <strong>eksctl</strong> successfully. </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="478" height="104" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-289.png" alt="Checking the eksctl CLI tool version " class="wp-image-12874" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-289.png 478w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-289-300x65.png 300w" sizes="(max-width: 478px) 100vw, 478px" /><figcaption> Checking the eksctl CLI tool version </figcaption></figure></div>
<p>If you’re new to <code>eksctl</code>, you can run the command below to get a list of all of the supported <code>eksctl</code> commands and their usage. </p>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">eksctl --help</code></pre>
</div>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1392" height="712" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-290.png" alt="Previewing the eksctl help page" class="wp-image-12875" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-290.png 1392w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-290-300x153.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-290-1024x524.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-290-768x393.png 768w" sizes="(max-width: 1392px) 100vw, 1392px" /><figcaption> Previewing the eksctl help page </figcaption></figure></div>
## Provisioning your EKS Cluster
<p>Now that you have configured eksctl, you can now provision your first EKS Cluster with <code>eksctl</code> commands.</p>
<p>Run the <code>eksctl</code> command below to create your first cluster and perform the following:</p>
<ul><li>Create a 3-node Kubernetes cluster named <code>dev</code> with one node type as <code>t3.micro</code> and region as <code>us-east-1</code>.</li><li>Define a minimum of one node (<code>--nodes-min 1</code>) and a maximum of four-node (<code>--nodes-max 4</code>) for this node group managed by EKS. The node group is named <code>standard-workers</code>.</li><li>Create a node group with the name <code>standard-workers</code> and select a machine type for the <code>standard-workers</code> node group.</li></ul>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">eksctl create cluster --name dev --version 1.21 --region us-east-1 --nodegroup-name standard-workers --node-type t3.micro --nodes 3 --nodes-min 1 --nodes-max 4 --managed</code></pre>
</div>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1897" height="522" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-291.png" alt="Provisioning your EKS Cluster" class="wp-image-12876" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-291.png 1897w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-291-300x83.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-291-1024x282.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-291-768x211.png 768w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-291-1536x423.png 1536w" sizes="(max-width: 1897px) 100vw, 1897px" /><figcaption> Provisioning your EKS Cluster </figcaption></figure></div>
<p>2. Navigate to your <a href="https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html" target="_blank" rel="noreferrer noopener">CloudFormation</a> dashboard to see the actions taken by the command. The <code>eksctl create cluster</code> command uses <a href="https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/Welcome.html" target="_blank" rel="noreferrer noopener nofollow">CloudFormation</a> to provision the infrastructure in your AWS account. </p>
<p>An <strong>eksctl-dev-cluster</strong> CloudFormation stack is being created. This process might take 15 minutes or more to complete. </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1608" height="243" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-292.png" alt="Previewing the eksctl-dev-cluster stack." class="wp-image-12877" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-292.png 1608w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-292-300x45.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-292-1024x155.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-292-768x116.png 768w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-292-1536x232.png 1536w" sizes="(max-width: 1608px) 100vw, 1608px" /><figcaption> Previewing the eksctl-dev-cluster stack. </figcaption></figure></div>
<p>3. Now, navigate to your EKS dashboard, and you’ll see a cluster named <strong>dev</strong> provisioned. Click on the <strong>dev</strong> hyperlink to access <strong>dev’s</strong> EKS Cluster dashboard. </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1571" height="330" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-293.png" alt="Navigating to the dev EKS Cluster dashboard." class="wp-image-12878" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-293.png 1571w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-293-300x63.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-293-1024x215.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-293-768x161.png 768w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-293-1536x323.png 1536w" sizes="(max-width: 1571px) 100vw, 1571px" /><figcaption> Navigating to the dev EKS Cluster dashboard. </figcaption></figure></div>
<p>Below, you can see the <strong>dev’s</strong> EKS cluster details, like <strong>Node name</strong>, <strong>Instance type</strong>, <strong>Node Group</strong>, and <strong>Status</strong>. </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1545" height="521" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-294.png" alt="Previewing the dev EKS Cluster dashboard." class="wp-image-12879" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-294.png 1545w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-294-300x101.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-294-1024x345.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-294-768x259.png 768w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-294-1536x518.png 1536w" sizes="(max-width: 1545px) 100vw, 1545px" /><figcaption> Previewing the dev EKS Cluster dashboard. </figcaption></figure></div>
<p>4. Switch to your EC2 dashboard, and you’ll see four nodes are running, with three having the <strong>t3.micro</strong> role in your AWS account (three worker nodes and one master node). </p>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1018" height="276" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-295.png" alt="Previewing the EC2 dashboard." class="wp-image-12880" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-295.png 1018w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-295-300x81.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-295-768x208.png 768w" sizes="(max-width: 1018px) 100vw, 1018px" /><figcaption> Previewing the EC2 dashboard. </figcaption></figure></div>
<p>5. Finally, run the command below to update your kubectl config (<code>update-kubeconfig</code>) with your cluster endpoint, certificate, and credentials. </p>
<div class="not-prose">
<pre class="wp-block-code"><code lang="bash" class="language-bash">aws eks update-kubeconfig --name dev --region us-east-1</code></pre>
</div>
<div class="wp-block-image">
<figure class="aligncenter size-full"><img decoding="async" loading="lazy" width="1059" height="79" src="https://adamtheautomator.com/wp-content/uploads/2022/01/image-296.png" alt="Updating kubectl config" class="wp-image-12881" srcset="https://adamtheautomator.com/wp-content/uploads/2022/01/image-296.png 1059w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-296-300x22.png 300w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-296-1024x76.png 1024w, https://adamtheautomator.com/wp-content/uploads/2022/01/image-296-768x57.png 768w" sizes="(max-width: 1059px) 100vw, 1059px" /><figcaption> Updating kubectl config </figcaption></figure></div>
<h1 id="gitlab-runner-helm-chart">GitLab Runner Helm Chart <span class="badge-trigger free"><a class="badges-drop" data-toggle="tooltip" data-placement="top" target="_blank" title="" href="https://about.gitlab.com/pricing/?glm_source=docs.gitlab.com&glm_content=badges-docs" data-original-title="On GitLab self-managed and GitLab SaaS, available in all tiers."><span><div class="badge-display badge-tier"></div></span></a></span><a href="https://docs.gitlab.com/runner/install/kubernetes.html#gitlab-runner-helm-chart" title="Permalink" class="anchor"></a>
</h1><div class="mt-3 admonition-wrapper note"><div class="admonition admonition-non-dismissable alert alert-note"><div>
<svg role="img" aria-label="note" class="gl-icon ml-1 mr-1 s16 alert-icon"><use href="/assets/images/icons.svg#information-o"></use></svg><div role="alert"><div class="alert-body">This chart has been tested on Google Kubernetes Engine and Azure Kubernetes Service.
Other Kubernetes installations may work as well, if not please
<a href="https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues">open an issue</a>.</div></div></div></div></div><p>The official way of deploying a GitLab Runner instance into your
Kubernetes cluster is by using the <code class="highlighter-rouge">gitlab-runner</code> Helm chart.</p><p>This chart configures GitLab Runner to:</p><ul>
<li>Run using the <a href="https://docs.gitlab.com/runner/executors/kubernetes.html">Kubernetes executor</a> for GitLab Runner.</li><li>For each new job it receives from GitLab CI/CD, provision a new pod within the specified namespace to run it.</li></ul><h2 id="prerequisites">Prerequisites<a href="https://docs.gitlab.com/runner/install/kubernetes.html#prerequisites" title="Permalink" class="anchor"></a>
</h2><ul>
<li>Your GitLab server’s API is reachable from the cluster.</li><li>Kubernetes 1.4+ with Beta APIs enabled.</li><li>The <code class="highlighter-rouge">kubectl</code> CLI installed locally and authenticated for the cluster.</li><li>The <a href="https://helm.sh/docs/using_helm/#installing-the-helm-client">Helm client</a> installed locally on your machine.</li></ul><h2 id="installing-gitlab-runner-using-the-helm-chart">Installing GitLab Runner using the Helm Chart<a href="https://docs.gitlab.com/runner/install/kubernetes.html#installing-gitlab-runner-using-the-helm-chart" title="Permalink" class="anchor"></a>
</h2><p>Add the GitLab Helm repository:</p><div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>helm repo add gitlab https://charts.gitlab.io
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>If using Helm 2, you must also initialize Helm:</p><div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>helm init
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>If you are unable to access to the latest versions of GitLab Runner, you should update the chart. To update the chart, run:</p><div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>helm repo update gitlab
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>To view a list of GitLab Runner versions you have access to, run:</p><div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>helm search repo <span class="nt">-l</span> gitlab/gitlab-runner
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>Once you <a href="https://docs.gitlab.com/runner/install/kubernetes.html#configuring-gitlab-runner-using-the-helm-chart">have configured</a> GitLab Runner in your <code class="highlighter-rouge">values.yaml</code> file,
run the following:</p><div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># For Helm 2</span>
helm <span class="nb">install</span> <span class="nt">--namespace</span> <NAMESPACE> <span class="nt">--name</span> gitlab-runner <span class="nt">-f</span> <CONFIG_VALUES_FILE> gitlab/gitlab-runner
<span class="c"># For Helm 3</span>
helm <span class="nb">install</span> <span class="nt">--namespace</span> <NAMESPACE> gitlab-runner <span class="nt">-f</span> <CONFIG_VALUES_FILE> gitlab/gitlab-runner
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>Where:</p><ul>
<li>
<code class="highlighter-rouge"><NAMESPACE></code> is the Kubernetes namespace where you want to install the GitLab Runner.</li><li>
<code class="highlighter-rouge"><CONFIG_VALUES_FILE></code> is the path to values file containing your custom configuration. See the
<a href="https://docs.gitlab.com/runner/install/kubernetes.html#configuring-gitlab-runner-using-the-helm-chart">Configuring GitLab Runner using the Helm Chart</a> section to create it.</li></ul><p>If you want to install a specific version of GitLab Runner Helm Chart, add <code class="highlighter-rouge">--version <RUNNER_HELM_CHART_VERSION></code>
to your <code class="highlighter-rouge">helm install</code> command. You can install any version of the chart
this way, however more recent <code class="highlighter-rouge">values.yml</code> may not work with an older version of the chart.</p><h2 id="upgrading-gitlab-runner-using-the-helm-chart">Upgrading GitLab Runner using the Helm Chart<a href="https://docs.gitlab.com/runner/install/kubernetes.html#upgrading-gitlab-runner-using-the-helm-chart" title="Permalink" class="anchor"></a>
</h2><p>Before upgrading GitLab Runner, pause the runner in GitLab and ensure any jobs have completed.
Pausing the runner prevents problems arising with the jobs, such as
<a href="https://docs.gitlab.com/runner/faq/index.html#helm-chart-error--unauthorized">authorization errors when they complete</a>.</p><p>Once your GitLab Runner Chart is installed, configuration changes and chart updates should be done using <code class="highlighter-rouge">helm upgrade</code>:</p><div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code>helm upgrade <span class="nt">--namespace</span> <NAMESPACE> <span class="nt">-f</span> <CONFIG_VALUES_FILE> <RELEASE-NAME> gitlab/gitlab-runner
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>Where:</p><ul>
<li>
<code class="highlighter-rouge"><NAMESPACE></code> is the Kubernetes namespace where GitLab Runner is installed.</li><li>
<code class="highlighter-rouge"><CONFIG_VALUES_FILE></code> is the path to values file containing your custom configuration. See the
<a href="https://docs.gitlab.com/runner/install/kubernetes.html#configuring-gitlab-runner-using-the-helm-chart">Configuring GitLab Runner using the Helm Chart</a> section to create it.</li><li>
<code class="highlighter-rouge"><RELEASE-NAME></code> is the name you gave the chart when installing it.
In the <a href="https://docs.gitlab.com/runner/install/kubernetes.html#installing-gitlab-runner-using-the-helm-chart">Installing GitLab Runner using the Helm Chart</a> section, we called it <code class="highlighter-rouge">gitlab-runner</code>.</li></ul><p>If you want to update to a specific version of GitLab Runner Helm Chart instead of the latest one, add <code class="highlighter-rouge">--version <RUNNER_HELM_CHART_VERSION></code>
to your <code class="highlighter-rouge">helm upgrade</code> command.</p><h2 id="check-available-gitlab-runner-helm-chart-versions">Check available GitLab Runner Helm Chart versions<a href="https://docs.gitlab.com/runner/install/kubernetes.html#check-available-gitlab-runner-helm-chart-versions" title="Permalink" class="anchor"></a>
</h2><p>Versions of Helm Chart and GitLab Runner do not follow the same versioning.
Use the command below to get version mappings between Helm Chart and GitLab Runner:</p><div class="language-shell highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="c"># For Helm 2</span>
helm search <span class="nt">-l</span> gitlab/gitlab-runner
<span class="c"># For Helm 3</span>
helm search repo <span class="nt">-l</span> gitlab/gitlab-runner
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>Example of the output is shown below:</p><div class="language-plaintext highlighter-rouge"><div class="highlight"><pre class="highlight"><code>NAME CHART VERSION APP VERSION DESCRIPTION
...
gitlab/gitlab-runner 0.14.0 12.8.0 GitLab Runner
gitlab/gitlab-runner 0.13.1 12.7.1 GitLab Runner
gitlab/gitlab-runner 0.13.0 12.7.0 GitLab Runner
gitlab/gitlab-runner 0.12.0 12.6.0 GitLab Runner
gitlab/gitlab-runner 0.11.0 12.5.0 GitLab Runner
gitlab/gitlab-runner 0.10.1 12.4.1 GitLab Runner
gitlab/gitlab-runner 0.10.0 12.4.0 GitLab Runner
...
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><h2 id="configuring-gitlab-runner-using-the-helm-chart">Configuring GitLab Runner using the Helm Chart<a href="https://docs.gitlab.com/runner/install/kubernetes.html#configuring-gitlab-runner-using-the-helm-chart" title="Permalink" class="anchor"></a>
</h2><p>Create a <code class="highlighter-rouge">values.yaml</code> file for your GitLab Runner configuration. See
<a href="https://helm.sh/docs/chart_template_guide/#values-files">Helm docs</a>
for information on how your values file will override the defaults.</p><p>The default configuration can always be found in the
<a href="https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/main/values.yaml"><code class="highlighter-rouge">values.yaml</code></a>
in the chart repository.</p><h3 id="required-configuration">Required configuration<a href="https://docs.gitlab.com/runner/install/kubernetes.html#required-configuration" title="Permalink" class="anchor"></a>
</h3><p>For GitLab Runner to function, your configuration file <strong>must</strong> specify the following:</p><ul>
<li>
<code class="highlighter-rouge">gitlabUrl</code> - the GitLab server full URL (e.g., <code class="highlighter-rouge">https://gitlab.example.com</code>) to register the runner against.</li><li>
<code class="highlighter-rouge">runnerRegistrationToken</code> -
The registration token for adding new runners to GitLab.
This must be <a href="https://docs.gitlab.com/ee/ci/runners/">retrieved from your GitLab instance</a>.
Set the token directly or <a href="https://docs.gitlab.com/runner/install/kubernetes.html#store-registration-tokens-or-runner-tokens-in-secrets">store it in a secret</a>.</li></ul><p>Unless you need to specify any additional configuration, you are
ready to <a href="https://docs.gitlab.com/runner/install/kubernetes.html#installing-gitlab-runner-using-the-helm-chart">install GitLab Runner</a>.</p><h3 id="additional-configuration">Additional configuration<a href="https://docs.gitlab.com/runner/install/kubernetes.html#additional-configuration" title="Permalink" class="anchor"></a>
</h3><div class="introduced-in">
<p><a href="https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/106">Introduced</a> <a href="https://docs.gitlab.com/runner/register#runners-configuration-template-file">configuration template</a> in Helm Chart 0.23.0. See <a href="https://gitlab.com/gitlab-org/charts/gitlab-runner/-/issues/222">deprecation issue</a>.</p></div><p>You can use a <a href="https://docs.gitlab.com/runner/register/index.html#runners-configuration-template-file">configuration template file</a>
to <a href="https://docs.gitlab.com/runner/executors/kubernetes.html#the-available-configtoml-settings">configure the behavior of GitLab Runner build pod within Kubernetes</a>.
You can use the configuration template to configure any field on the runner,
without having the Helm chart be aware of specific runner configuration options.</p><p>Here’s a snippet of the default settings <a href="https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/main/values.yaml">found in the <code class="highlighter-rouge">values.yaml</code> file</a> in the chart repository. It is important to note that, for the <code class="highlighter-rouge">config:</code> section, the format should be <code class="highlighter-rouge">toml</code> (<code class="highlighter-rouge"><parameter> = <value></code> instead of <code class="highlighter-rouge"><parameter>: <value></code>), as we are embedding <code class="highlighter-rouge">config.toml</code> in <code class="highlighter-rouge">values.yaml</code>.</p><div class="language-yaml highlighter-rouge"><div class="highlight"><pre class="highlight"><code><span class="na">runners</span><span class="pi">:</span>
<span class="na">config</span><span class="pi">:</span> <span class="pi">|</span>
<span class="s">[[runners]]</span>
<span class="s">[runners.kubernetes]</span>
<span class="s">image = "ubuntu:16.04"</span>
</code><button class="clip-btn" title="Click to copy" data-selector="true"><svg class="gl-icon ml-1 mr-1 s16"><use xlink:href="/assets/images/icons.svg#copy-to-clipboard"></use></svg></button></pre></div></div><p>The executor-specific configuration <a href="https://gitlab.com/gitlab-org/charts/gitlab-runner/blob/main/values.yaml">is documented in the <code class="highlighter-rouge">values.yaml</code></a>.</p>
Editor is loading...