Skip to main content
Version: 1.8

Configuration Settings

General Settings

cluster

  • endpoint: The public endpoint of your Kubernetes cluster. It will be used by Okteto when generating Kubeconfig credentials for your users.
cluster:
endpoint: "https://52.30.32.1"

license

Okteto is free for small teams. You can manage up to 3 users without having to provide a license.

license: XXXXX

Want to use Okteto with a bigger team? Let's talk

You can also use a secret to store the license.

subdomain

Okteto's automatic SSL endpoints allows you to expose secure and unique public endpoints for your development environments. By default, all endpoints created by Okteto will use a combination of the name of the app, the namespace, and the subdomain. For example, if you have a development environment named app in the cindy namespace, it will be accessible at https://app-cindy.example.com if subdomain is example.com.

subdomain: "example.com"

Okteto's frontend and API services will be also accessible via https://okteto.$SUBDOMAIN. Once Okteto is installed, you can use kubectl to retrieve the public address of the Okteto NGINX Ingress Controller:

kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto

The output will look something like this:

NAME                              TYPE           CLUSTER-IP   EXTERNAL-IP     PORT(S)                                     AGE
okteto-ingress-nginx-controller LoadBalancer 10.0.7.73 34.68.230.234 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m

You'll need to take the EXTERNAL-IP address to create a DNS entry for *.$SUBDOMAIN.

You can overwrite Okteto's public URL using the publicOverride field.

publicOverride

Use this property to override the Public URL where Okteto is available. This option replaces okteto.$SUBDOMAIN with your FQDN of choice.

publicOverride: "example.com"

Important: When using publicOverride, the certificate referred by wildcardCertificate.name must be valid for publicOverride, registry.$SUBDOMAIN and buildkit.$SUBDOMAIN.

When publicOverride is set, an additional component is deployed for Okteto Private Endpoints feature. You can configure its settings using the privateEndpoints section.

When setting your auth provider, the authentication callback URL and origin URL will change to the following:

Callback URL:

https://${publicOverride}/auth/callback
https://private-endpoints.${subdomain}/auth/callback

Origin URL:

https://${publicOverride}
https://private-endpoints.${subdomain}

auth

Okteto supports the following authentication methods:

Bitbucket

Follow Bitbucket's official documentation on how to create an OAuth Consumer.

When creating the OAuth Consumer, you will need to provide the following values:

Callback URL:

https://okteto.DOMAIN/auth/callback

URL:

https://okteto.DOMAIN

Permissions: Account: Email Account: Read

Use this group of settings when using Bitbucket OAauth as your authentication provider.

auth:
bitbucket:
enabled: true
clientId: OAauth Consumer Key
clientSecret: OAauth Consumer Secret
workspace: my-workspace

You can also use a secret to store the sensitive part of these credentials.

The workspace field is optional. Only members of the workspace will be allowed to login into your Okteto instance. An empty workspace field permits any user to log in.

GitHub

If you are planning on using the GitHub Integration, you should follow this guide. You'll then use the same Github Application for the Integration as the one from Oauth.

Follow GitHub's official documentation on how to create an OAuth App.

When creating the OAuth App, you will need to provide the following values:

Homepage URL:

https://okteto.DOMAIN

Authorization callback URL:

https://okteto.DOMAIN/auth/callback

Use this group of settings when using GitHub OAuth as your authentication provider.

auth:
github:
enabled: true
clientId: clientID
clientSecret: clientSecret
organization: my-org

You can also use a secret to store the sensitive part of these credentials.

The organization field is optional. Only members of the organization will be allowed to log in into your Okteto instance. An empty organization field permits any user to log in.

Google

Follow Google's official documentation on how to create an OAuth 2.0 Client.

When creating the OAUTH 2.0 Client, you will need to provide the following values:

Authorized javascript origin:

https://okteto.DOMAIN

Authorized redirect URIs:

https://okteto.DOMAIN
https://okteto.DOMAIN/auth/callback

Use this group of settings when using Google OAuth as your authentication provider.

auth:
google:
enabled: true
clientId: clientid.apps.googleusercontent.com
clientSecret: clientSecret
allowDomains:
- example.com

You can also use a secret to store the sensitive part of these credentials.

The allowDomains field is optional. Only users with Google Workspace accounts that match one of the domains on the list will be allowed to log into your Okteto instance. An empty allowDomains field permits any user with a valid Google Workspace account to log in.

OpenID Connect

Follow your OpenID Connect service provider's documentation on how to create the required application.

Okteto supports any identity provider that implements the OpenID Connect standard. The following external identity providers have been tested with Okteto:

Are we missing your favorite identity provider? Open a feature request in the Okteto Community and let us know!

When creating the application, you'll need to provide the following values:

  • Start SSO URL: https://okteto.DOMAIN
  • Redirect URIs: https://okteto.DOMAIN, https://okteto.DOMAIN/auth/callback
  • Scopes: openid, email, profile
  • Response Type: code
  • Grant Type: authorization code

Use this group of settings when using an OpenID Connect provider as your authentication provider.

auth:
openid:
enabled: true
clientId: clientid
clientSecret: clientSecret
group: my-group
endpoints:
issuer: https://your-provider
authorization: https://your-provider/authorization
mapping:
externalIDKey: nickname
nameKey: name
emailKey: email
pictureKey: picture
groupsKey: groups

You can also use a secret to store the sensitive part of these credentials.

The group field is optional. Only members of the group will be allowed to log in into your Okteto instance. An empty group field permits any user to log in.

The issuer and authorization endpoints must match the value returned in the provider config discovery.

The mapping fields are optional. Use them to configure the mapping between Okteto's user attributes and the claim coming from your authentication provider.

Your provider needs to support the UserInfo endpoint in order to be used with Okteto. This authentication option follows the OpenID standard, and it has been validated with Okta, PingIdentity, and GitLab.

Token

Okteto defaults to token-based authentication to simplify the installation and configuration of Okteto self-hosted.

This enables you to use a token for a single user, login to the Okteto UI, and start exploring Okteto's features and functionality much faster than configuring other authentication methods. Other authentication methods are more time-consuming and cumbersome to configure.

Once you've completed the initial configuration of Okteto using token-based authentication and explored the product, you can then switch to another authentication method. Token-based authentication would no longer be ideal as you expand to multiple users and incorporating production environments into Okteto.

auth:
token:
enabled: true

Follow our post-installation notes to learn how to login to the Okteto UI and configure your Okteto CLI with a randomly generated token.

Okteto Components

api

The API service. Account and Kubernetes credentials management, namespace creation, and sharing, deployment via the catalog, etc...

  • annotations: Annotations to add to the API pods.
  • extraEnv: Environment variables to be set on the API containers.
  • labels: Labels to add to the API pods.
  • replicaCount: The number of API pods. It defaults to 2.
  • resources: The resources for the API pods.
api:
extraEnv:
- name: NO_PROXY
value: ".example.com"
replicaCount: 2
resources:
requests:
cpu: 100m
memory: 128Mi

autoscaler

The cluster autoscaler service. Disabled by default. It instructs the Kubernetes cluster autoscaler to scale nodes if the real cpu/memory usage of a node is beyond the limits. Use tolerations.devPool to limit the autoscaler analysis to a subset of cluster nodes.

Requirements: cluster autoscaler and metrics server must be installed in your cluster.

  • annotations: Annotations to add to the autoscaler pods.
  • cpu.up: Increase the cluster size when the CPU consumption is greater than or equal to this value. It defaults to 60 percent.
  • cpu.down: Decrease the cluster size when the CPU consumption is lesser than this value. It defaults to 40 percent.
  • image: image used by the autoscaler to deploy the autoscaler agent. It defaults to busybox.
  • labels: Labels to add to the autoscaler pods.
  • memory.up: Increase the cluster size when the Memory consumption is greater than or equal to this value. It defaults to 70 percent.
  • memory.down: Decrease the cluster size when the Memory consumption is lesser than this value. It defaults to 50 percent.
  • nodes.increment: The number of new nodes to request when all the current nodes are overloaded. e.g. if this value is 3, the autoscaler will request 3 new nodes when all the cluster nodes are overloaded. It defaults to 1.
  • nodes.min: Minimum number of nodes in the cluster. It defaults to 1.
  • nodes.max: Maximum number of nodes in the cluster. It defaults to 10. Zero means unlimited.
  • nodes.poolLabel: The node label that identifies the node pool of the node. For example, the value in GKE is cloud.google.com/gke-nodepool. In EKS the value is eks.amazonaws.com/nodegroup. If set, the autoscaler scales each node pool independently.
  • pods.up: Increase the cluster size when the Pods in a node vs the max pods per node is greater than or equal to this value. It defaults to 90 percent.
  • pods.down: Decrease the cluster size when the Pods in a node vs the max pods per node is lesser than this value. It defaults to 80 percent.
  • schedule: How often, in seconds, the autoscaler analyzes if the cluster needs to be scaled. It defaults to 300.
  • slackWebhook: A slack webhook url to notify autoscaler events.
  • volumes.up: Increase the cluster size when the Volumes in a node vs the max volumes per node is greater than or equal to this value. It defaults to 90 percent.
  • volumes.down: Decrease the cluster size when the Volumes in a node vs the max volumes per node is lesser than this value. It defaults to 80 percent.
autoscaler:
enabled: false
image: busybox
schedule: 300
cpu:
up: 60
down: 40
memory:
up: 70
down: 50
pods:
up: 90
down: 80
volumes:
up: 90
down: 80
nodes:
increment: 1
min: 1
max: 10
podLabel: cloud.google.com/gke-nodepool
slackWebhook:

buildkit

The build service. It's used in combination with okteto build to build containers directly in the cluster.

  • port: Port used for the buildkit statefulset. Defaults to 443.
  • annotations: Annotations to add to the buildkit pods.
  • extraEnv: Environment variables to be set on the buildkit containers.
  • hpa.enabled: Enable horizontal pod autoscaling for the buildkit pods. Disabled by default.
  • hpa.min: Minimum number of buildkit pods to keep running.
  • hpa.max: Maximum number of buildkit pods to scale to.
  • hpa.cpu: The amount of CPU utilization that will cause the HPA to scale the buildkit pods.
  • labels: Labels to add to the buildkit pods.
  • podManagementPolicy: The podManagementPolicy of the buildkit pods. Defaults to Parallel.
  • replicaCount: The number of buildkit pods. It defaults to 1.
  • resources: The resources for the buildkit pods.
  • serviceAccount.create: create a service account for buildkit. True by default.
  • serviceAccount.name: Buildkit service account name. Defaults to okteto-buildkit.
  • serviceAccount.annotations: Annotations for the buildkit service account.
  • serviceAccount.labels: Labels for the buildkit service account.
  • persistence.enabled: Configures a persistence volume for buildkit. False by default.
  • persistence.storageClass: The storage class of the persistence volume attached to every buildkit pod.
  • persistence.size: The size of the persistence volume attached to every buildkit pod. Defaults to 750Gi.
  • persistence.cache: The size (in Mi) of the buildkit cache to store image caches. It should be around 30Gi smaller than storage.size. Defaults to 500Gi.
  • service.sessionAffinity: The sessionAffinity setting for the buildkit service. None by default.
buildkit:
port: 443
extraEnv:
- name: NO_PROXY
value: ".example.com"
replicaCount: 1
persistence:
enabled: true
storageClass: ssd
size: 180Gi
cache: 150000

In order to handle timeouts during communication between the client and the buildkit daemon, the following environment variables can be modified on the server side:

  • OKTETO_KEEPALIVE_SERVER_TIME_MS: After this duration of time, if the server doesn't see any activity it pings the client to see if the transport is still alive. If set below 1s, a minimum value of 1s will be used. The current default value is 2 hours.
  • OKTETO_KEEPALIVE_SERVER_TIMEOUT_MS: After having pinged for keepalive check, the server waits for a duration of Timeout and if no activity is seen, the connection is closed. The current default value is 20 seconds.
  • OKTETO_KEEPALIVE_SERVER_MAX_CONN_IDLE_MS: Duration for the amount of time after which an idle connection would be closed by sending a GOAWAY. Idleness duration is defined since the most recent time the number of outstanding RPCs became zero or the connection establishment. The current default value is infinity.
  • OKTETO_KEEPALIVE_SERVER_MAX_CONN_AGE_MS: Duration for the maximum amount of time a connection may exist before it will be closed by sending a GOAWAY. A random jitter of +/-10% will be added to the value to spread out connection storms. The current default value is infinity.
  • OKTETO_KEEPALIVE_SERVER_MAX_CONN_AGE_GRACE_MS: An additive period after OKTETO_KEEPALIVE_SERVER_MAX_CONN_AGE_MS after which the connection will be forcibly closed. The current default value is infinity.
  • OKTETO_KEEPALIVE_SERVER_POLICY_MINTIME_MS: Minimum amount of time a client should wait before sending a keepalive ping. The current default value is 5 minutes.
  • OKTETO_KEEPALIVE_SERVER_POLICY_PERMIT_WITHOUT_STREAM: If true, server allows keepalive pings even when there are no active streams(RPCs). If false, and client sends pings when there are no active streams, server will send GOAWAY and close the connection. False by default.

daemonset

The daemonset automatically configures every node of your cluster to work better with Okteto.

  • annotations: Annotations to add to the daemonset pods.
  • extraEnv: Environment variables to be set on the daemonset containers.
  • labels: Labels to add to the daemonset pods.
  • image: Container image used by the daemonset pods.

The daemonset performs the following tasks on each node:

  • Overrides the Okteto Registry hostname resolution to use internal IPs.
  • Overrides the default kernel values for file watchers on every node.
  • Configures the kubelet with registry credentials for private registries.
  • Installs your CA if wildcardCertificate.privateCA is enabled.
  • Installs a CA if using self-signed certificates (wildcardCertificate.create: true).

You can restrict the nodes where the daemonset is deployed using tolerations:

tolerations:
devPool: dev

defaultBackend

The defaultBackend receives errored requests from the ingress-controller and transform them returning them to the client.

  • affinity: Affinities to add to the defaultBackend pods.
  • annotations: Annotations to add to the defaultBackend pods.
  • enabled: Control if defaultBackend is deployed. Defaults to true.
  • extraEnvs: Environment variables to be set on the defaultBackend containers.
  • image: Configuration block to customize the image used by the defaultBackend pods.
    • repository: Registry and repository for the defaultBackend pods.
    • tag: Tag used for the defaultBackend pods.
  • labels: Labels to add to the defaultBackend pods.
  • nodeSelector: Labels to select on which nodes defaultBackend pods will be scheduled.
  • port: Internal port used for the defaultBackend. Defaults to 8080.
  • replicaCount: The number of defaultBackend pods. It defaults to 2.
  • resources: The resources for the defaultBackend pods.
  • tolerations: The toletations for the defaultBackend pods.
defaultBackend:
replicaCount: 3
resources:
requests:
cpu: 100m
memory: 128Mi

The defaultBackend provides the following features:

  • Autowake namespaces: when a user access an endpoint from an slept namespace, the defaultBackend will issue a wake command.
  • Custom error pages: when a user access an endpoint and an error is produced, the defaultBackend will return a custom error page with hints on how to solve it.

You can also restrict the nodes where the defaultBackend is deployed using tolerations:

tolerations:
devPool: dev

frontend

The frontend service serves the web application.

  • annotations: Annotations to add to the frontend pods.
  • extraEnv: Environment variables to be set on the frontend containers.
  • labels: Labels to add to the frontend pods.
  • replicaCount: The number of frontend pods. It defaults to 2.
  • resources: The resources for the frontend pods.
frontend:
extraEnv:
- name: NO_PROXY
value: ".example.com"
replicaCount: 2
resources:
requests:
cpu: 100m
memory: 128Mi

gc

The garbage collector service. It automatically scales idle applications to zero and deletes unused namespaces. Enabled by default.

  • annotations: Annotations to add to the gc pods.
  • labels: Labels to add to the gc pods.
  • scaleToZeroPeriod: The duration, in hours, that an application or resource must be idle before the garbage collector scales it to zero. Set to zero to disable.
  • deleteNamespacePeriod: The duration, in days, that a namespace must be idle before the garbage collector deletes it. Set to zero to disable.
  • slackWebhook: If set, the garbage collector will send a notification when it scales a resource to zero or when it deletes a namespace.
gc:
enabled: true
scaleToZeroPeriod: 24
deleteNamespacePeriod: 15
slackWebhook:

installer

The jobs that deploy your development environments from Git.

  • annotations: Annotations to add to the installer job pods.
  • extraEnv: Environment variables to be set on the installer job containers.
  • labels: Labels to add to the installer job pods.
  • image: to configure your custom installer binaries, including a custom Okteto CLI version.
  • runner: to configure your custom installer image.
  • activeDeadlineSeconds: Maximum duration of the pipeline in seconds.
  • gitSSHUser: User to be used when cloning git repos using ssh.
  • sshSecretName: The name of the secret that contains the private key used when cloning git repos using ssh. If it doesn't exist, the key and the secret will be automatically generated by Okteto.
  • resources: The resources for pods created by the installer jobs.
installer:
image: okteto/installer:1.5.2
runner: okteto/pipeline-runner:1.0.0
extraEnv:
- name: NO_PROXY
value: ".example.com"
activeDeadlineSeconds: 1800
gitSSHUser: git
sshSecretName: "okteto-ssh"
resources:
requests:
cpu: 10m
memory: 50Mi

registry

The private container registry.

  • annotations: Annotations to add to the registry pods.
  • extraEnv: Environment variables to be set on the registry containers.
  • ingress.annotations: Annotations to add to the registry ingress. These annotations take precendence over the ones defined in the ingress section.
  • labels: Labels to add to the registry pods.
  • pullPolicy: The security policy for image pulls. If set to cluster, any Okteto user can pull any image from the registry. When set to namespace, only users with access to the namespace can pull images from the namespace. It defaults to namespace.
  • replicaCount: The number of registry pods. It defaults to 1.
  • resources: The resources for the registry pods.
  • serviceAccountName: Alternative service account to be used by the registry. The service account must exist in the same namespace for the Okteto Helm release. Defaults to none.
  • serviceAccount.annotations: Annotations to add to the registry service account.
  • secret.name: when using external storage, the name of the secret with the values of your cloud provider credentials.
  • secret.accessKey: the key of the access key in the secret referenced by secret.name (defaults to accessKey).
  • secret.secretKey: the key of the secret key in the secret referenced by secret.name (defaults to secretKey).
  • storage: The storage mechanism for the images.

storage

Okteto supports different storage drivers to store the images inside the Okteto Registry.

filesystem

Set filesystem.enabled to true if you want to store the images in the container filesystem. Additionally, set filesystem.persistence.enabled to true if you want to store the images in a PVC attached to the registry. Both options might limit your ability to scale up the registry, depending on the type of storage you are using. You can also customize the storageClass (optional), the size of the volume (defaults to 40Gi), or attach an existing volume claim via claimName.

registry:
storage:
filesystem:
enabled: true
persistence:
enabled: true
claimName: ""
accessMode: ReadWriteOnce
storageClass: ""
size: 40Gi
azure

Use this to use Azure Storage to store your private images.

STORAGE_ACCOUNT_ACCESS_KEY refers to a storage account access key with read/write permissions to the storage container specified in the Okteto configuration. Create a secret with the value of STORAGE_ACCOUNT_ACCESS_KEY using the command below.

$ kubectl create secret generic okteto-registry-secret --namespace=okteto --from-literal=secretKey=STORAGE_ACCOUNT_ACCESS_KEY

Then, add the following configuration to your Okteto helm values file:

registry:
storage:
provider:
azure:
enabled: true
storage:
container: "storage-container-name"
accountName: "service-account-name"
aws

Use this to use S3 to store your private images.

Use this option to give the registry pods a role to authenticate with the S3 bucket.

To do that, add the following configuration to your Okteto helm values file:

registry:
storage:
provider:
aws:
enabled: true
bucket: "bucket-name"
region: "aws-region"
iam:
enabled: false
serviceAccount:
annotations:
eks.amazonaws.com/role-arn: 'arn:aws:iam::111122223333:role/okteto-registry-role-name'
IAM User

IAM_SECRET_KEY refers to the secret key of an IAM with read/write permissions to the bucket specified in the Okteto configuration. Create a secret with the value of IAM_SECRET_KEY using the command below.

$ kubectl create secret generic okteto-registry-secret --namespace=okteto --from-literal=secretKey=IAM_SECRET_KEY

Then, add the following configuration to your Okteto helm values file:

registry:
storage:
provider:
aws:
enabled: true
bucket: "bucket-name"
region: "aws-region"
iam:
enabled: true
accessKeyID: "XXXXXX"
digitalocean

Use this to use DigitalOcean Spaces to store your private images.

ACCESS_KEY refers to the access key of the storage space specified in the Okteto configuration. Create a secret with the value of ACCESS_KEY using the command below.

$ kubectl create secret generic okteto-registry-secret --namespace=okteto --from-literal=secretKey=ACCESS_KEY

Then, add the following configuration to your Okteto helm values file:

registry:
storage:
provider:
digitalocean:
enabled: true
space:
name: "space-name"
accessKeyID: "access-key"
gcp

Use this to use Google Cloud Storage to store your private images.

Use this option to configure the registry pods with a workload id to authenticate with the bucket.

To do that, add the following configuration to your Okteto helm values file:

registry:
storage:
provider:
gcp:
enabled: true
bucket: "bucket-name"
project: "project-id"
workloadIdentity:
enabled: true
serviceAccount:
annotations:
iam.gke.io/gcp-service-account: 'GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com'
Service Account Key (JSON)

key.json refers to a file containing the key of a service account with read/write permissions to the storage bucket specified in the Okteto configuration. Create a secret with the value of key.json using the command below.

$ kubectl create secret generic okteto-registry-secret --namespace=okteto --from-file=key=key.json

Then, add the following configuration to your Okteto helm values file:

registry:
storage:
provider:
gcp:
enabled: true
bucket: "bucket-name"
project: "project-id"

telemetry

You can enable or disable the telemetry job. The telemetry job "phones home" once a day with the following information:

  • Number of managed users
  • Number of managed namespaces
  • Kubernetes Version and Platform
  • A unique install ID
  • Your license ID.
  • The name of the authentication provider
  • The name of the cloud provider

Okteto uses the information to help us better understand how our customers use Okteto, as well as to help us prioritize fixes and features. We don't share your information with anyone else.

telemetry:
enabled: true

If this configuration is disabled, Okteto CLI analytics are automatically disabled.

webhook

The webhook service. Ingress creation, generation of hostnames, enforcement of policies, etc...

  • annotations: Annotations to add to the webhook pods.
  • extraEnv: Environment variables to be set on the webhook containers.
  • hostNetwork: Enables or disables host networking for the webhook deployment. The default is false.
  • labels: Labels to add to the webhook pods.
  • port: Port sets the port used for the webhook deployment. The default is 443.
  • replicaCount: The number of webhook pods. It defaults to 2.
  • resources: The resources for the webhook pods.

Advanced Configuration

affinity

Apply default affinities to pods deployed in namespaces created by Okteto.

  • devPool: Affinities for pods created on namespaces managed by Okteto.
  • oktetoPool: Affinities for pods created during the Okteto installation.
affinity:
devPool:
preferredDuringSchedulingIgnoredDuringExecution:
- preference:
matchExpressions:
- key: cloud.google.com/spot
operator: In
values:
- "true"
weight: 10
oktetoPool:
preferredDuringSchedulingIgnoredDuringExecution:
- preference:
matchExpressions:
- key: dev.okteto.com/overloaded
operator: DoesNotExist
weight: 50

In this case, pods deployed in namespaces created by Okteto will have a preferred affinity to land on preemptible nodes.

applications

  • repository: The Helm repository available for every developer. This is disabled by default. To enable, set the applications.repository property to your Helm registry URL
applications:
repository: "https://apps.okteto.com"

clusterRole

Okteto assings this cluster role to every user via a namespace-scoped role binding. The default value assigns each developer a cluster-admin role binding with only access to their personal namespaces.

clusterRole: "cluster-admin"

user extraRoleBindings

Extra RoleBindings to be created for every user's service account. This is useful if you want to grant access to resources in other namespaces of the cluster. Disabled by default.

The RoleBindings will reference ClusterRoles and will be scoped to the namespace specified in the configuration. Okteto will not create neither the ClusterRoles nor the Namespaces and expects them to exist in the cluster. Here's an example configuration:

user:
extraRoleBindings:
enabled: true
roleBindings:
namespace-name1:
- cluster-role1
- cluster-role2
namespace-name2:
- cluster-role3

convertLoadBalancedServices

Converts services with type LoadBalancer into ClusterIP and automatically creates an ingress. Enabled by default.

convertLoadBalancedServices:
enabled: true

crds

Configures CRDs managed by Okteto

  • annotations: The annotations to apply to the CRDs created during the Okteto installation.
  • keep: Keep CRDs on chart uninstall (defaults to true).
  • install: Install and upgrade CRDs on chart install (defaults to true).
crds:
install: true
keep: true
annotations: {}

devStorageClass

Uses the specified storage class for all persistent volume claims created when developers execute okteto up. This setting will override any storage class defined on the Okteto manifest. Disabled by default.

  • storageClass: The storage class enforced for persistent volume claims created by okteto up.
devStorageClass:
enabled: true
storageClass: ebs-sc

There is only one exception where this storage class is overwritten. In case of having volume snapshots feature configured, if a storage class is required for the snapshots that storage class will have preference.

globalClusterRole

Okteto assings this cluster role to every user via a cluster role binding. By default, this behavior is disabled. This can be useful to give access to cluster level resources to every developer account, like accessing the Node API.

globalClusterRole: ""

ingress

Configure default values for the ingress created by Okteto.

  • annotations: The annotations to apply to all the ingresses created during the Okteto installation.
  • oktetoIngressClass: The ingressClassName to apply to all the ingresses created during the Okteto installation (defaults to nginx).
  • class: If specified, Okteto will set this as the ingressClassName of all ingresses managed by Okteto. This is useful if you have more than one ingress controller in your cluster.
  • forceIngressClass: If enabled, all ingresses deployed in namespaces managed by Okteto will have the ingress class defined in ingress.class (default: false).
  • forceIngressSubdomain: If enabled, the subdomain of the host of all ingresses deployed in namespaces managed by Okteto must match the okteto wildcard subdomain (default: true).
  • ip: The internal IP of the ingress. Pods will call the Okteto API and the Okteto Registry using this IP. Required if the installation of the Okteto NGINX Ingress Controller is disabled.
ingress:
annotations: {}
oktetoIngressClass: nginx
class: nginx
forceIngressClass: false
forceIngressSubdomain: true
ip: ""

ingressLimits

Configure ingress connections limits for each public endpoint. Disabled by default.

  • connections: Maximum parallel connections for each ingress.
  • rps: Maximum requests per second for each ingress.
  • rpm: Maximum requests per minute for each ingress.
ingressLimits:
enabled: true
connections: 40
rps: 40
rpm: 400

injectDevelopmentBinaries

Automatically inject kubectl, helm, and okteto binaries on every development environment, and on the git and helm deployment pipelines. This requires permissions to mount a host volume.

If this is disabled, you'll need to provide your own image in installer.image.

injectDevelopmentBinaries:
enabled: true

namespace

Annotation and label customizations in namespaces created by Okteto. These annotations and labels are additional to the ones already applied by Okteto.

  • annotations: Annotations applied to each namespace created by Okteto.
  • labels: Labels applied to each namespace created by Okteto.
  • ingress.annotations: Annotations applied to ingresses in namespaces created by Okteto.
  • ingress.labels: Labels applied to ingresses in namespaces created by Okteto.
namespace:
annotations:
development: "true"
labels:
istio-injection: enabled
ingress:
annotations:
cert-manager.io/issuer: "letsencrypt"
labels:
development: "true"

networkPolicies

Configures network policies for each namespace to isolate network traffic. Disabled by default.

  • ingress: Ingress list of rules (NetworkPolicyIngressRule) to be applied on every namespace managed by Okteto. (optional).
  • egress: Egress list of rules (NetworkPolicyEgressRule) to be applied on every namespace managed by Okteto (optional).
networkPolicies:
enabled: true
ingress:
- from:
- ipBlock:
cidr: 172.17.0.0/16
except:
- 172.17.1.0/24
- namespaceSelector:
matchLabels:
project: myproject
- podSelector:
matchLabels:
role: frontend
ports:
- protocol: TCP
port: 6379
egress:
- to:
- ipBlock:
cidr: 10.0.0.0/24
ports:
- protocol: TCP
port: 5978

podSecurityPolicy

Decide if you want pod security policy to be added to the service accounts created by Okteto.

enabled

Whether to enable pod security policy (defaults to true).

useAppArmor

Add the apparmor security annotations to the Okteto pod security policies. (defaults to true).

If true the following annotations are added to the existing pod security policy:

apparmor.security.beta.kubernetes.io/allowedProfileNames: runtime/default
apparmor.security.beta.kubernetes.io/defaultProfileName: runtime/default
podSecurityPolicy:
enabled: true
useAppArmor: true

overrideFileWatchers

Overrides the default kernel values for file watchers in every node. Recommended if you're running databases, or if you plan on using "okteto up" on the cluster. This requires permission to mount and modify /proc values.

  • maxUserWatches: The maximum number of allowed inotify watchers.
  • maxMapCount: The maximum number of memory map areas a process may have.
  • aioMaxNR: The maximum number of allowable concurrent IO requests.
overrideFileWatchers:
enabled: true
maxUserWatches: 10048576
maxMapCount: 262144
aioMaxNR: 1000000

overrideRegistryResolution

Overrides the registry hostname resolution to use internal IPs. This requires permission to mount and modify the cluster nodes' /etc/hosts file.

overrideRegistryResolution:
enabled: true

prepullImages

Pre-pull the git and helm installer images in all the nodes. This requires permission to mount the docker socket.

prepullImages:
enabled: true

privateRegistry

A list of private registries and its corresponding credentials. The kubelet will use them when pulling images:

privateRegistry:
hub:
url: https://index.docker.io/v1/
user: username1
password: password1
gcr:
url: https://gcr.io
token: dXNlcjM6cGFzc3dvcmQzCg==
aws:
url: 536194259215.dkr.ecr.us-east-1.amazonaws.com
user: $AWS_ACCESS_KEY_ID
password: $AWS_SECRET_ACCESS_KEY

Use token if your registry does not support username/password authentication (e.g. google registry).

If you are using an AWS private registry, Okteto takes care of refreshing docker credentials every 4 hours.

You can use this to configure a Docker Hub account for your cluster in order to avoid DockerHub's pull limits. Be careful, a credential misconfiguration could lead to an issue where kubelet cannot pull public images from Docker Hub. If this happens, follow these instructions to recover from this state.

pullAlways

Forces the PullAlways image pull policy in the cluster. Enabled by default.

pullAlways:
enabled: true

quickstarts

The list of shortcuts to show in the "Deploy from Git Repository" dialog.

  • name: Name to identify the quickstart.
  • url: Repository URL configured for the quickstart.
  • branch: Default branch to be considered for the configured quickstart repository.
  • variables: List of variables to be passed to the pipeline on deployment time.
    • name: Indicates the variable name.
    • value: Specifies the default value.
    • options: Specifies an enumeration of possible values.
  • default: Flag to indicate if url, branch and variables fields will be automatically filled with configured values in the "Deploy from Git Repository" dialog.
quickstarts:
- name: "Movies Sample App"
url: https://github.com/okteto/movies
default: true
branch: main
variables:
- name: DB_HOST
value: mongodb
- name: THEME
options: ["dark", "light"]
- name: "GitHub"
url: https://github.com/
- name: "GitLab"
url: https://gitlab.com/
- name: "Bitbucket"
url: https://bitbucket.org/

quotas

Enables resource quotas at the namespace level.

  • resources: Limits the number of resources that a user can create.
    • maxNamespaces: Maximum number of namespaces.
    • maxPods: Maximum number of pods per namespace.
    • maxReplicationControllers: Maximum number of replication controllers per namespace.
    • maxSecrets: Maximum number of secrets per namespace.
    • maxServices: Maximum number of services per namespace.
    • maxLoadBalancers: Maximum number of services of type LoadBalancer per namespace.
    • maxNodePorts: Maximum number of services of type NodePort per namespace.
    • maxConfigMaps: Maximum number of config maps per namespace.
    • maxPVCs: Maximum number of persistent volume claims per namespace.
    • maxVolumeSnapshots: Maximum number of volume snapshots per namespace.
    • maxIngresses: Maximum number of ingresses per namespace
  • bandwidth: Limits the incoming/outcoming bandwidth per pod. Requires using the Okteto NGINX Ingress Controller.
    • ingress: Maximum ingress bandwidth.
    • egress: Maximum egress bandwidth.
    • up: Limits the incoming/outgoing bandwidth per development container.
      • ingress: Maximum ingress bandwidth for a development container
      • egress: Maximum egress bandwidth for a development container.
  • requests: Limits the maximum resource requests per namespace.
    • cpu: Maximum CPU resource requests.
    • memory: Maximum memory resource requests.
    • storage: Maximum storage resource requests.
  • limits: Limits the maximum resource limits per namespace.
    • cpu: Maximum CPU resource limits.
    • memory: Maximum memory resource limits.
    • storage: Maximum storage resource limits.
  • limitranges: Configures the limit ranges of each namespace.
    • max: Configures the maximum resources per container.
      • cpu: Maximum CPU resource limits.
      • memory: Maximum memory resource limits.
    • requests: Configures the default resource requests per container.
      • cpu: Default CPU resource requests.
      • memory: Default memory resource requests.
    • limits: Configures the default resource limits per container.
      • cpu: Default CPU resource limits.
      • memory: Default memory resource limits.

The default values are:

quotas:
resources:
enabled: false
maxNamespaces: "3"
maxPods: "20"
maxServices: "20"
maxReplicationControllers: "30"
maxSecrets: "50"
maxConfigMaps: "50"
maxPVCs: "10"
maxVolumeSnapshots: "10"
bandwidth:
enabled: false
ingress: "800M"
egress: "800M"
requests:
enabled: false
cpu: "1"
memory: "2Gi"
storage: "20Gi"
limits:
enabled: false
cpu: "4"
memory: "8Gi"
storage: "20Gi"
limitranges:
max:
enabled: false
cpu: "3"
memory: "12Gi"
requests:
enabled: true
cpu: "100m"
memory: "0.2Gi"
limits:
enabled: true
cpu: "2"
memory: "8Gi"

secret

Labels and annotations to include in the secret created by the chart. Useful if you want to integrate with Vault or similar secret stores.

secret:
annotations:
your.custom.annotation: "10"
labels:
your.custom.label: "20"

tolerations

Indicates tolerations for the okteto components. Define the label and taint okteto-node-pool on your worker nodes to match these values.

  • oktetoPool: Tolerations for the api, webhook, gc, autoscaler, ingress controller, and frontend services.
  • buildPool: Tolerations for the buildkit and registry services.
  • devPool: Tolerations for the pods deployed in namespaces created by okteto.
tolerations:
oktetoPool: okteto
buildPool: build
devPool: dev

For example, if you add the label okteto-node-pool:build and the taint okteto-node-pool=build:NoSchedule to a node, and you are using buildPool: build, the buildkit and registry pods are deployed to this node.

userDefinedNamespaces

Disable if you want to enforce using the username as a suffix on namespaces and ingress hosts. Enabled by default.

userDefinedNamespaces: false

userPodAffinity

When enabled Okteto automatically adds a preferred affinity to every pod, which leans towards placing pods from the same namespace and in the same node (default: true).

  • antiAffinity: When enabled Okteto adds an anti-affinity to the pod to ensure that all pods in the same namespace are placed in the same node. Disabled by default
userPodAffinity:
enabled: true
antiAffinity:
enabled: false

virtualServices

When enabled, the Okteto UI will show the public endpoints associated with Istio Virtual Services (default: false).

virtualServices:
enabled: false

volumes

Allows you to specify different settings for volumes.

  • validate: Section to configure volume validation.
  • enabled: Enables volume validation. Disabled by default
  • supportedStorageClasses: List of supported storage classes.
  • forceStorageClass: Flag to specify if the storage class should be enforced in case of creating a volume with a non-supported storage class. If set, the first storage class specified on supportedStorageClasses will be the enforced value.
  • supportedAccessModes: List of supported access modes.
volumes:
validate:
enabled: true
supportedStorageClasses: ["standard", "standard-rwo"]
forceStorageClass: true
supportedAccessModes: ["ReadWriteOnce"]

volumeSnapshots

Enables users to initialize persistent volume claims with the contents of a preexisting volume snapshot.

This feature requires having a CSI driver installed in your cluster.

  • driver: The name of the CSI driver used when creating snapshots.
  • class: The VolumeSnapshotClass of the volume snapshot.
  • storageClass: The storage class required by volumes initialized from snapshots (optional).
  • enableNamespaceAccessValidation: When enabled, only users that have access to the namespace where the volume snapshot is stored will be able to use it in their development environments. Default false.
  • allowIDAnnotation: Allow using your cloud provider's snapshot ID as the source of the data. Default true.
volumeSnapshots:
enabled: true
driver: ebs.csi.aws.com
class: snapclass
storageClass: ebs-sc

Add the dev.okteto.com/from-snapshot-id annotation to any persistent volume claim to tell Okteto to initialize your persistent volume claim, as shown below:

apiVersion: v1
kind: PersistentVolumeClaim
metadata:
annotations:
dev.okteto.com/from-snapshot-id: snap-xxxxxxxx
name: pvc-name
spec:
accessModes:
- ReadWriteOnce
resources:
requests:
storage: 10Gi

When a persistent volume claim resource is created, Okteto will import the snapshot in Kubernetes using a VolumeSnapshotContent and will set the source of your persistent volume claim to this VolumeSnapshotContent.

wildcardCertificate

Disable if you want to bring your own certificates and/or certificate authority. Enabled by default.

  • create: If set to false, Okteto will not create the wildcard certificate automatically.
  • duration: The duration of the certificate. Ignored if create is set to false.
  • name: The name of the secret where the certificate will be stored.
  • privateCA.enabled: Set to true when using a private certificate authority.
  • privateCA.secret.name: The name of the secret that stores the private certificate authority's certificate.
  • privateCA.secret.key: The key in the secret that stores the private certificate authority's certificate.
wildcardCertificate:
create: true
duration: 2160h0m0s
name: default-ssl-certificate
# if using a private CA, specify the name of the TLS secret that stores the certificate
privateCA:
enabled: false
secret:
name: "okteto-ca"
key: "ca.crt"

user

serviceAccount

The configured annotations and labels are additional to the ones already applied by Okteto.

  • annotations: Annotations added to each service account generated by Okteto for user accounts.
  • labels: Labels added to each service account generated by Okteto for user accounts.
user:
serviceAccount:
annotations:
custom.annotation/one: one
custom.annotation/two: two
labels:
custom.label/one: one
custom.label/two: two

A common use case for adding service account annotations is to get access via IAM Roles or Workload Identity to create Cloud resources as part of your Okteto Manifest deploy commands.

privateEndpoints

When publicOverride is set, Okteto Self Hosted deploys an additional component for Okteto Private Endpoints feature, which is responsible for authenticating and authorizing requests sent to Okteto Endpoints set to private mode.

  • port: Internal port used for the Private Endpoint component. Defaults to 8080.
  • resources: The resources for the Private Endpoint component pods.
  • replicaCount: The number of Private Endpoint component pods. It defaults to 1.
  • annotations: Annotations to add to the Private Endpoint component pods.

By default, the Private Endpoint component will inherit the configuration set at the [auth] section, but you can override some values with the following properties:

  • clientID: Overrides auth.*.clientID.
  • clientSecret: Overrides auth.*.clientSecret.

Dependencies

Okteto will automatically install two instances of NGINX Ingress Controller as part of the default installation, using its official Helm chart.

Each instance has an specific role:

  • ingress-nginx: ingress-controller that serves all the inbound traffic to the Okteto cluster, including Buildkit, Registry, Okteto API, Okteto Frontend and users' ingresses.
  • okteto-nginx: ingress-controller dedicated to serve users' ingresses inbound traffic. By default, it is deployed behind ingress-nginx.

NGINX Ingress Controller

Use the ingress-nginx and okteto-nginx keys in your configuration file to modify the configuration.

For example, to change the number of replicas in ingress-nginx, you'd need to add the following:

ingress-nginx:
controller:
replicaCount: 2

The full list of values is available here.

Okteto ingress-nginx/okteto-nginx default values

Okteto sets specific values on the embedded ingress-nginx chart to enable features dependend on the ingress-controller. The values can be checked with the following command:

  • ingress-nginx:

    helm get values okteto/okteto --jsonpath '{.ingress-nginx}'
  • okteto-nginx:

    helm get values okteto/okteto --jsonpath '{.okteto-nginx}'

Using Your Own Ingress Controller

You can disable the installation of the main ingress-nginx with the following snippet:

ingress-nginx:
enabled: false

In that case, configure ingress.oktetoIngressClass with the ingress class you want to use for all the ingresses created during the Okteto installation. And the ingress.ip field with the Cluster IP of your ingress controller.

The okteto-nginx will continue to work and it will receive traffic with destintion *.$(SUBDOMAIN) from an ingress object at the release namespace. It can also be disabled with the following snippet:

okteto-nginx:
enabled: false

If okteto-nginx is disabled, the following features will stop working:

  • Autowake Namespaces
  • Error Pages
  • Private Endpoints

Cloud Provider Secret

Create a secret named okteto-cloud-secret to store the following values instead of setting them in your helm configuration file:

  • OKTETO_LICENSE: use this instead of .Values.license in your helm configuration file.
  • GOOGLE_CLIENTSECRET: use this instead of .Values.auth.google.clientSecret in your helm configuration file.
  • GITHUB_CLIENTSECRET: use this instead of .Values.auth.github.clientSecret in your helm configuration file.
  • BITBUCKET_CLIENTSECRET: use this instead of .Values.auth.bitbucket.clientSecret in your helm configuration file.
  • OPENID_CLIENTSECRET: use this instead of .Values.auth.openid.clientSecret in your helm configuration file.
  • GITHUB_INTEGRATION_CLIENTSECRET: use this instead of .Values.github.clientSecret in your helm configuration file.
  • GITHUB_APP_PRIVATE_KEY: use this instead of .Values.github.appPrivateKey in your helm configuration file.