Install the Codefresh Runner on your Kubernetes cluster to run pipelines and access secure internal services without compromising on premise security requirements. These pipelines run on your infrastructure, even behind the firewall, and keep code on your Kubernetes cluster.

Install the Codefresh Runner on your Kubernetes cluster to run pipelines and access secure internal services without compromising on-premises security requirements. These pipelines run on your infrastructure, even behind the firewall, and keep code on your Kubernetes cluster.

[Skip to quick installation→](#installation-with-the-quick-start-wizard)

in clustersthat areused for_deployment_. It is possible to deploy applications ondifferentclusters other than the ones the runner isrunning on.

in clusters used for_deployment_. It is possible to deploy applications on clusters other than the ones the runner isdeployed on.*

The installation process takes care of allthe componentsof the runner as well as theother resources (config-maps, secrets, volumes) needed by them.

The installation process takes care of allrunner componentsandotherrequiredresources (config-maps, secrets, volumes).

In order touse the Codefresh runneryou needthe following:

Touse the Codefresh runner the following is required:

1. A Kubernetes cluster with outgoingInternet access (with version later than 1.10). Each node should have 50GB disk size.

1. A container runtime such as[docker](https://kubernetes.io/blog/2020/12/02/dockershim-faq/),[containerd](https://containerd.io/) or[cri-o](https://cri-o.io/). Note that the runner is**NOT** dependent on any special dockershim features, so any compliant container runtimewill work.

1. A[Codefresh account]({{site.baseurl}}/docs/getting-started/create-a-codefresh-account/) with the Hybrid feature enabled.

1. A[Codefresh CLI token]({{site.baseurl}}/docs/integrations/codefresh-api/#authentication-instructions) that will be used to authenticate your Codefresh account.

1. A Kubernetes cluster with outgoinginternet access (for version later than 1.10). Each node should have 50GB disk size.

2. A container runtime, such as[docker](https://kubernetes.io/blog/2020/12/02/dockershim-faq/),[containerd](https://containerd.io/) or[cri-o](https://cri-o.io/). Note that the runner is**not** dependent on any special dockershim features, so any compliant container runtimeis acceptable.

3. A[Codefresh account]({{site.baseurl}}/docs/getting-started/create-a-codefresh-account/) with the Hybrid feature enabled.

4. A[Codefresh CLI token]({{site.baseurl}}/docs/integrations/codefresh-api/#authentication-instructions) that will be used to authenticate your Codefresh account.

Installationcanhappenfrom any workstation or laptopthat hasaccess (i.e. via`kubectl`) to the Kubernetes clusterthat will run Codefresh builds. The Codefresh runner will authenticate to your Codefresh account by using the Codefresh CLI token.

The runnercanbe installedfrom any workstation or laptopwithaccess (i.e. via`kubectl`) to the Kubernetes clusterrunning Codefresh builds. The Codefresh runner will authenticate to your Codefresh account by using the Codefresh CLI token.

You can obtain an API Key from your[user settings page](https://g.codefresh.io/user/settings).

Notice thataccess to the Codefresh CLI is only needed once during the Runner installation. After that, the Runner will authenticate on it own using the details provided. You do*NOT* need to install the Codefresh CLI on the cluster that is running Codefresh pipelines.

***Note:**access to the Codefresh CLI is only needed once during the Runner installation. After that, the Runner will authenticate on it own using the details provided. You do NOT need to install the Codefresh CLI on the cluster that is running Codefresh pipelines.*

Then run the wizard with the following command

The wizard will askyou some basic questions and proceed with the installation.

Brefore proceeding with installation, the wizard asksyou some basic questions.

{% include image.html

lightbox="true"

max-width="100%"

%}

The wizardwillalsocreate andrun a sample pipeline that you can see in your Codefresh UI

The wizard alsocreates andruns a sample pipeline that you can see in your Codefresh UI.

{% include image.html

lightbox="true"

That's it! You can now start using the Runner.

You can also verify your installation with

You can also verify your installation with:

During installation youwill alsosee which API token will be used by the runner (if you don't provide one by yourself). The tokenthatisprinted isused by the runner to talk to the Codefresh platformand it carriespermissions thatallows the runner to run pipelines.If younote downthe token, it can later be usedif the deployment is deletedto restore the runner's permissions without creating a new runner installation.

During installation youcansee which API token will be used by the runner (if you don't provide one). Theprintedtoken is used by the runner to talk to the Codefresh platformcarryingpermissions thatallow the runner to run pipelines. If yousavethe token, it can later be used to restore the runner's permissions without creating a new runner installation, if the deployment is deleted.

You can customize the wizard installation by passing your own values in the`init` command.

For example you can specify the runtimethat will be used in advance with:

For example you can specify the runtimeto be used in advance with:

{: .table .table-bordered .table-hover}

| Parameter| Description|

| --------------| ----------------------------|

| name| The name of the agentthat will be created.|

| token| Codefresh account token to be usedto install the Codefresh Runner.|

| url| Codefresh system custom url.|

| name| The name of the agentto be created.|

| token|TheCodefresh account token to be usedfor installing the Codefresh Runner.|

| url|TheCodefresh system custom url.|

| kube-context-name| Name of the Kubernetes context on which the runner should be installed|

| kube-node-selector| The Kubernetes node selector "key=value" to be used by runner resources (default is no node selector)|

| yes|Use installation defaults (don't ask any questions during the installation)|

| set-default-runtime| Set this as the default runtime environment for your Codefresh account|

| exec-demo-pipeline| Run a demo pipeline after the installation completes (true/false)|

| kube-namespace| Name of the namespaceon whichthe runnershould be installed|

| tolerations| The Kubernetes tolerations as path to aJSON file to be used by the runner resources (default is no tolerations)|

| storage-class-name| Set a nameof your custom storage class|

| kube-config-path| Path to kubeconfig file (default is $HOME/.kube/config)|

| set-value| Pass a custom parameter/value pair|

| verbose| Print logs|

| docker-daemon-access| Allows direct Docker daemon access (default true)|

| yes|This enables installation defaults (don't ask any questions during the installation)|

| set-default-runtime| Set this as the default runtime environment for your Codefresh account.|

| exec-demo-pipeline| Run a demo pipeline after the installation completes. (true/false)|

| kube-namespace| Name of the namespacewherethe runnerwill be installed.|

| tolerations| The Kubernetes tolerations asapath to a JSON file to be used by the runner resources. (default: no)|

| storage-class-name| Set a namefor your custom storage class.|

| kube-config-path| Path to kubeconfig file (default is $HOME/.kube/config).|

| set-value| Pass a custom parameter/value pair.|

| verbose| Print logs.|

| docker-daemon-access| Allows direct Docker daemon access. (default: true)|

Alternatively you can pass a values.yml file to the`init` command that includes all installation settings:

Alternatively, you can pass a values.yml file to the`init` command that includes all installation settings:

Once installed the Runner is fully automated. It polls on its own the Codefresh SAAS (by default every ten seconds) and

creates automatically all resources needed for running pipelines.

Once installed, the Runner is fully automated. It polls the Codefresh SAAS (by default every ten seconds) on its own and automatically creates all resources needed for running pipelines.

Once installation is complete, you should see the cluster of the runner as a new[Runtime environment](https://g.codefresh.io/account-admin/account-conf/runtime-environments) in Codefreshat your*Account Settings*, in the respective tab.

Once installation is complete, you should see the cluster of the runner as a new[Runtime environment](https://g.codefresh.io/account-admin/account-conf/runtime-environments) in Codefreshin your*Account Settings*, in the respective tab.

{% include image.html

lightbox="true"

max-width="60%"

%}

If you have multiple environments available, you can change the defaultone(shown with a thin blue border) by clicking on the 3 dot menu on the right of each environment. The Codefresh runner installer comes withan option`set-default` thatwill automatically setas default the new runtime environment.

If you have multiple environments available, you can change the default (shown with a thin blue border) by clicking on the 3 dot menu on the right of each environment. The Codefresh runner installer comes witha`set-default`optionthatis automatically setby default in the new runtime environment.

You can even override the runtime environment for a specific pipeline by specifying in the respective section in the[pipeline settings]({{site.baseurl}}/docs/configure-ci-cd-pipeline/pipelines/).

You can uninstall the Codefresh runner from your cluster by running

You can uninstall the Codefresh runner from your cluster by running:

A wizard similar to the installationone, will ask you questions regarding your cluster before finishing with the removal.

A wizard, similar to the installationwizard, will ask you questions regarding your cluster before finishing with the removal.

Like the installation wizard you can pass the following options in advance as command line parameters:

Like the installation wizard, you can pass the following options in advance as command line parameters:

{: .table .table-bordered .table-hover}

| Parameter| Description|

| --------------| ----------------------------|

| name| The name of the agentthat will be created.|

| url| Codefresh system custom url.|

| kube-context-name| Name of the Kubernetes context on which the runner should be installed|

| name| The name of the agentto be created.|

| url|TheCodefresh system custom url.|

| kube-context-name| Name of the Kubernetes context on which the runner should be installed.|

| kube-namespace| Name of the Kubernetes namespace from which the Codefresh agent and runtime will be removed.|

| kube-config-path| Path to kubeconfig file (default is $HOME/.kube/config)|

| verbose| Print logs|

| verbose| Print logs.|

|`dind-volume-provisioner`| 300m| 400Mi| Doesn't need PV| Pod| Yes|

|`dind-lv-monitor`| 300m| 400Mi| Doesn't need PV| DaemonSet| Yes|

Components that are always on consume resources all the time. Components that are not always on only consumeresource when pipelines are running (they are created and destroyed automatically for each pipeline).

Components that are always on consume resources all the time. Components that are not always on only consumeresources when pipelines are running (they are created and destroyed automatically for each pipeline).

Node size and count willentirelydepend on how many pipelines you want to be “ready” for and how many will use “burst” capacity.

Node size and count will depend entirely on how many pipelines you want to be “ready” for and how many will use “burst” capacity.

* Ready (nodes): Lower initialization time and faster build times.

* Burst (nodes): High initialization time and slower build times. (Not recommended)