okteto / docs Goto Github PK

License: Apache License 2.0

JavaScript 0.36% SCSS 0.14% Dockerfile 0.01% MDX 99.50%

docs's Introduction

Okteto: A Tool to Develop Applications on Kubernetes

Overview

Kubernetes has made it very easy to deploy applications to the cloud at a higher scale than ever, but development practices have not evolved at the same speed as application deployment patterns.

Today, most developers try to either run parts of the infrastructure locally or just test their integrations directly in the cluster via CI jobs, or the docker build/redeploy cycle. It works, but this workflow is painful and incredibly slow.

okteto accelerates the development workflow of Kubernetes applications. You write your code locally and okteto detects the changes and instantly updates your Kubernetes applications.

How it works

Okteto enables development inside a container, providing a seamless IDE and tool integration as if you were working locally but with the resources of a remote cluster. When you run okteto up your Kubernetes deployment is replaced by a Development Container that contains your development tools (e.g. maven and jdk, or npm, python, go compiler, debuggers, etc). This development container can use any docker image. The development container inherits the same secrets, configmaps, volumes or any other configuration value of the original Kubernetes deployment.

The end result is a remote cluster that is seen by your IDE and tools as a local filesystem/environment. You keep writing code on your local IDE and as soon as you save a file, the change goes to the development container, and your application instantly updates (taking advantage of any hot-reload mechanism you already have). This whole process happens in an instant. No docker images need to be created and no Kubernetes manifests need to be applied to the cluster.

Why Okteto

okteto has several advantages when compared to more traditional development approaches:

Fast inner loop development: build and run your application using your favorite tools directly from your development container. Native builds are always faster than the docker build/redeploy cycle.
Realistic development environment: your development container reuses the same variables, secrets, sidecars, volumes as your original Kubernetes deployment. Realistic environments eliminate integration issues.
Replicability: development containers eliminate the need to install your dependencies locally, everything is pre-configured in your development image.
Unlimited resources: get access to the hardware and network of your cluster when developing your application.
Deployment independent: okteto decouples deployment from development. You can deploy your application with kubectl, Helm, a serverless framework, or even a CI pipeline and use okteto up to develop it. This is especially useful for cloud-native applications where deployment pipelines are not trivial.
Works anywhere: okteto works with any Kubernetes cluster, local or remote. okteto is also available for macOS, Linux, and Windows.

Getting started

All you need to get started is to install the Okteto CLI and have access to a Kubernetes cluster. You can follow our guide for setting up a Kubernetes cluster on AWS here.

The Okteto CLI has two operational modes:

Okteto Open Source CLI
Okteto Platform CLI

Okteto Open Source CLI Features

Okteto Open Source requires access to a Kubernetes cluster. It's designed to support Development Containers in any Kubernetes cluster. It doesn't come with features that support multiple developers working on the same cluster. That's the goal of the Okteto Platform

Okteto Open Source supports the following commands:

okteto context
okteto up
okteto down

For reference, our Open Source CLI supports the dev section of the Okteto Manifest.

We have getting started guides for the Open Source mode for the following languages:

Okteto Platform CLI Features

The Okteto Platform CLI requires installation of the Okteto Helm Chart in your Kubernetes cluster. In this mode, all of the Okteto CLI commands are available (build, deploy, up, down, destroy, etc). The Okteto Platform comes with additional features like:

User authentication and access control to Kubernetes using your own Identity provider
Build service for remote container image creation
Preview environments for every pull request
Dynamic scaling of environments based on usage
Secrets manager for your development environments
Okteto Insights to provide observability on your development environments

And much more! Refer to the Okteto Platform docs to learn more.

Features Comparison

Feature	Okteto Open Source CLI	Okteto Platform CLI
Development Containers	Available	Available
Build Service	Not Available	Available
User Management	Not Available	Available
Access Control	Not Available	Available
Automated Scaling	Not Available	Available
Secrets Management	Not Available	Available
Observability Tools	Not Available	Available
Support	Community Support	Professional Support
Documentation	Open Source Samples	Platform Docs

Useful links

Releases

Okteto is monthly released into three channels: stable, beta, and dev. By default when Okteto is installed, the stable channel is used. If you need to access features not yet widely available you can install from the beta or dev channel. More information can be found in the release documentation.

Support and Community

Got questions? Have feedback? Join the conversation in our Community Forum. You can also join us in the #okteto Slack channel! If you don't already have a Kubernetes Slack account, sign up here.

Follow @OktetoHQ on Twitter for important announcements.

✨ Contributions

We ❤️ contributions big or small. See our guide on how to get started.

Thanks to all our contributors!

docs's People

Contributors

Stargazers

Watchers

Forkers

davidpthomas flou21 omnomagonz hosamalmoghraby abs007 nitishfy anshulangaria jeremyphua cmilesq sd-13 websitekupro indratensei orbit-love wssb12345678

docs's Issues

Document the github helm configuration values

Currently, the values described on https://www.okteto.com/docs/enterprise/administration/github/#adding-the-github-app-configuration-to-okteto are not documented anywhere else.

I believe that we should include them on https://www.okteto.com/docs/enterprise/install/deployment/#configuration-file

Expand the search engine

I don't know if it's the right place to put this issue

It gets really hard to find the correct information across the different places (docs, community, posts, github repos). It would be nice to have the search bar from the docs be able to search across different pages to reduce the complexity when searching, and the docs would be the go-to place for finding anything (as they would redirect with the search)

document how to set okteto context for vanilla clusters

Adding or deleting vanilla clusters to the kubeconfig adds them to the list of contexts. But this information isn't documented anywhere in the docs clearly.

Document how `okteto` namespace can be used in the registry to store content with read access to all Okteto users

We had several times a question about how to make an image in the Okteto built-in registry available with read access to all the Okteto users. We implemented some time ago that feature, but we didn't document it yet.

How to use the feature:

Any Okteto admin should be able to push images to okteto namespace. That can be done in 2 different ways:

Using the long notation <okteto-registry-url>/okteto/<image-name>
Using the short notation okteto.global/<image-name>

This will push any image or helm chart artifact to the okteto namespace and any Okteto user will be able to pull that image (both notations explained above are valid).

We should also bear in mind the scenario for helm chart artifacts when including this doc: #108

"How to" optimize Dockerfiles with Buildkit series

add documentation about a use case using okteto registry to store helm charts

We need to add some kind of documentation, probably in the form of a blog post or something similar in the okteto community. This post should include a common use case for working with the okteto registry as a chart store where in a particular repo you have the definition of the charts and in each merge these are packed and stored in the okteto registry. After that, the developers work with in their developments making pull of the last changes of the charts loaded in the okteto registry.

more context:

document details about how okteto cli works

Reference: #55 (comment)

We could also have this information in Okteto CLI GitHub wiki instead of the docs.

Document how helm chart are supported in Okteto's built-in registry

We had a discussion in our community forum about the helm chart support in Okteto's built-in registry. After some testing, we support that scenario and it would be nice to include some documentation explaining how to use it. I'll include some information on how it works but feel free to ping me directly if you have any question about how it works

The use case is to use Okteto's registry to store helm chart artifacts in the same way we store images. To do so, you can follow the next intructions.

helm registry login -u <user> <okteto-registry-url>
Password:
Login Succeeded

If your helm chart wasn't packaged yet, you can do it executing:

helm package <folder-with-chart-definition>
Successfully packaged chart and saved it to: <path-to-helm-artifacts-tgz>

Once you have your helm chart packaged, you can push it to the Okteto registry using the following command. Important note, you need to specify the Okteto namespace (at the end of the registry url) where the artifacts will be pushed in the same way it is done when pushing an image:

helm push <path-to-helm-artifacts-tgz> oci://<okteto-registry-url>/<okteto-namespace>
Pushed: <okteto-registry-url>/<okteto-namespace>/<helm-chart-name>:<version>
Digest: sha256:07805....

Now, you (or any other Okteto user with access to the Okteto namespace) should be able to pull the chart with the following command:

helm pull oci://<okteto-registry-url>/<okteto-namespace>/<helm-chart-name> --version <version>
Pulled: <okteto-registry-url>/<okteto-namespace>/<helm-chart-name>:<version>
Digest: sha256:0780569....

In the community forum I added an example on how to do it with Cloud and one of the helm charts defined in the movies example. I'll include it also here to illustrate how to apply the steps defined above. For this example, I will assume the movies repo is cloned locally.

First thing, we should login into the Okteto Cloud registry using our Okteto Cloud credentials:

helm registry login -u <user> registry.cloud.okteto.net
Password:
Login Succeeded

Lets go to the root folder of the cloned movies app and lets package the helm chart

helm package api/chart
Successfully packaged chart and saved it to: /Users/xxxx/xxxxx/xxxxx/xxxx/movies-api-0.1.0.tgz

Once the chart is packaged, lets push it to Cloud's registry

helm push /Users/xxxx/xxxxx/xxxxx/xxxxxx/movies-api-0.1.0.tgz oci://registry.cloud.okteto.net/<okteto-namespace>
Pushed: registry.cloud.okteto.net/<okteto-namespace>/movies-api:0.1.0
Digest: sha256:07805....

Now, you can verify everything was pushed correctly trying to pull the chart:

helm pull oci://registry.cloud.okteto.net/<okteto-namespace>/movies-api --version 0.1.0
Pulled: registry.cloud.okteto.net/<okteto-namespace>/movies-api:0.1.0
Digest: sha256:0780569....

Document how to link a node dependency to a local folder

From auth0 and katana:

We link npm packages to services as volumes from time to time when we're developing some of our own npm packages.

Document how to use Okteto Stack fragments

For reference, this is how it is documented in the compose spec:
https://github.com/compose-spec/compose-spec/blob/master/spec.md#fragments

Document Persist Bash History Between Iterations of a Dev Cluster

Show in the docs how history can be shared across iterations a dev container for an app. For this persistent volume feature should be enabled.

Solution creates a volume where history is stored and restored when a new dev container is created.

Document different okteto environment variables

There are environment variables that can be set by an user but there is no documentation such as:

OKTETO_DISABLE_SPINNER: Disables the okteto spinner
OKTETO_RESCAN_INTERVAL: Syncthing rescan interval
OKTETO_TOKEN: Connects to the k8s with this token
OKTETO_URL: Defines the okteto cluster url

Feedback: Install Okteto Enterprise in Google Kubernetes Engine

https://okteto.com/docs/enterprise/gke/

Small enhancements

At "Requirements -> Deploy a Kubernetes cluster", use vocabulary more related to GCP (e.g. stable channel).
At "Requirements -> Creating the Google OAuth application", point that the type of oauth2 client app must be web application.
At "Requirements -> Subdomain", rename section to "Create a Cloud DNS zone" and explain how it is used by the bundled cert-manager (e.g. it creates a TXT record to validate ownership of the FQDN and emit a certificate).
At "Installing Okteto Enterprise -> Creating the Okteto namespace", broken link to configuration example.
- https://github.com/okteto/website/pull/856

Suggestions

At "Requirements -> Creating a Google Cloud Service Account", rework the section by using Workload Identity (https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity).
At "Requirements", add command examples on how to boostrap infrastructure.
- If resources are available, create public repository with IaaC examples (e.g. "Want to automate it with terraform? Check this link!").

Link to install the CLI is broken

Not sure if the app is broken, or the docs changed the link. But going to the link below results in a 404

Add importance of specifying [devName] for `okteto up`

The docs for okteto up needs some info that specifies the importance of using[devName] in okteto up.
https://www.okteto.com/docs/reference/cli/#up

ServiceAccount Configuration is missing (Okteto Manifest Reference)

Hello,

a couple days ago I wanted to run a pod with a specific serviceaccount using okteto.

After checking the manifest reference documentation here: https://www.okteto.com/docs/reference/manifest/
I thought it was not possible

But I found that issue okteto/okteto#867 and this pr https://github.com/okteto/okteto/pull/1344/files

So it is possible and it was pretty simple to use.
I wanted to add this missing part to the documentation.
But after reading the contribution guide I thought it's maybe better to first create this issue.

Create `Administration` section in the docs

Users of Okteto Scale and Okteto Enterprise have access to an administration panel. As part of the effort of making our docs more focused on the scenarios, instead of self-host vs SaaS, I think it's important to show case the 'Admin' features at the same level as 'Development Environments' and 'Preview Environments'.

This section should contain:

the admin dashboard (what today lives in https://www.okteto.com/docs/enterprise/administration/dashboard/)
Namespace cleanup (https://www.okteto.com/docs/enterprise/administration/cleanup/)
https://www.okteto.com/docs/enterprise/administration/private-repositories/github-app/
https://www.okteto.com/docs/enterprise/administration/private-repositories/ssh-key/
https://www.okteto.com/docs/enterprise/administration/volume-snapshots/ (we should break this into two sections, one on how to use it (using the values we use for cloud and scale), and one on how to configure it for self-hosted.
Cluster secrets

We now support a badge for 'Starter', 'Scale', and 'Enterprise'. We should also add 'SaaS' and 'Self-hosted' to the list of badges and properly label the pages according to what applies for SaaS (SaaS = okteto cloud + okteto for teams) and what applies for self-hosted

Kubernetes version support matrix

We need a matrix to easily discover which kubernetes versions support each okteto version. Right now, it's hard to get this information. As a sample, this is what nginx ingress controller does:
https://github.com/kubernetes/ingress-nginx/tree/helm-chart-4.4.0#supported-versions-table

"Helm configuration file" vs "Configuration file" terms

👋 - This might be just my confusion, but it seemed valuable to capture in case it was helpful 😊

When I am deploying Okteto, according to https://www.okteto.com/docs/self-hosted/install/deployment/ (or perhaps one of the Cloud Provider Guides) I'm seeing the term "Configuration file". In the cloud guides it might also be "Okteto GKE configuration file" or "Okteto EKS configuration file"

In the next step, I use Helm and I specify this file. It is (I believe a "Helm configuration file"), but that wasn't obvious to me at first. I thought it was a specific "okteto" file.

Where I got really confused is when I was told to "...add the following to your Helm configuration file..." (ref) I wasn't sure if my "Helm configuration file" was in fact the same file I used to install Okteto in the first place, or something else? 😅

It's also mentioned in a few other spots, sometimes referred to as "config.yaml", but I'm pretty sure it's the same thing.

Would it be possible to use a more consistent term for this file, and perhaps always link back to a single place that explains it?

Document healthchecks field in /docs/reference/compose/

@jLopezbarb we should document all the fields we support in the Compose spec.
And document a list of the fields that we don't support

Document the requirement to install the GitHub App in the GitHub organization filtered in the auth provider section

Currently, when you configure GitHub as authenticator provider in an Okteto instance, you can specify a setting called organization to allow only members of that GitHub Organization to login into Okteto.

For this setting to work properly, the GitHub App used in Okteto to authenticate users should be installed in the configured GitHub in order to be able to know if users logging in to Okteto belongs to that organization or not. We should document this fact because it is really important and we don't have it documented yet.

More context in this slack thread: https://okteto.slack.com/archives/C02T9BKMS4V/p1647222612204739

Generate release notes from structured data

To be able to automate the release notes, we need as a first step to render them in place from structured data (json, yaml, etc). This will allow us to more easily update them on a new release with whatever strategy we see fit moving forward.

We could first start with semi-automating a PR into this repo but then move into a more elaborate workflow where we generate the versioned docs automatically via a okteto/app new-release webhook event.

Perform final 1.0 merge of docs and release versioned docs for 1.0

Add documentation to the dev.okteto.com/inject-token annotation

Adding the annotation

dev.okteto.com/inject-token: "true"

to the okteto manifest will the the webhook to add the env OKTETO_TOKEN with the uid to de dev container.

Maybe we should find a place to document this

Sample for working with `npm link`

removed actions and broken links in Okteto documentation

In the GitHub Actions Documentation page, some actions were removed from the Github Actions marketplace but there are still listed in the documentation page and links of these actions are not valid anymore.
https://www.okteto.com/docs/cloud/github-actions/#available-actions

List of the removed actions from the marketplace but still shown in the documentation page:

Create doc for Cloud new network quotas

Only show the last 5 versions of the docs in the dropdown

navigation tree shows that the 'endpoints' command is part of the 'down' command

Document labels used by Okteto pods

Is your feature request related to a problem? Please describe.
Documentation request

Describe the solution you'd like
In my case, I use a wrapper around some K8s tools including Okteto to abstract some complexity, and am also using KEDA autoscaling to scale my app. When I start Okteto, the autoscaler interferes because it automatically starts its own non-Okteto pods, so traffic is then split between Okteto pods and the autoscaler pods, causing problems and confusion. For this reason, I changed my CLI so that before starting Okteto it patches the services so that they send traffic only to the Okteto pods, ignoring the autoscaled pods. So I can work with Okteto just fine.

This wasn't documented, so I had to figure out that Okteto labels the pod for the main service with the label "interactive.dev.okteto.com" and the additional services (as specified in the manifest) with "detached.dev.okteto.com".

By patching my services to use these labels during an Okteto session, I no longer have problems due to the autoscaling.

Describe alternatives you've considered
I couldn't think of an alternative

Documentation for Github PR Previews

As part of the preview environment github integration we need to update the docs to properly document the auto previews PR integration.

This is the page: https://www.okteto.com/docs/cloud/preview-environments/preview-environments-github/

Not sure if the idea is to deprecate the github action or not but we would need to either replace the page or create a new one.

convert tutorials to blogs + documentation pages

Update screenshots with the new “Launch Dev Environment” and “Dev Environment” labels

Once the onboarding is released the changes in the UI must be reflected on the docs screenshots (https://github.com/okteto/app/pull/3481)

CLI 2.0 Migration Guides for 0.12 Chart Release

The upgrade to 2.0 can be cumbersome and frustrating for a user that already has a project setup on 1.x. In order to address this we need a migration guide that spells out any places where 2.0 might be backwards incompatible.

Document the CRDs available on Okteto and their version

I think we should have a doc with a list of the CRDs available

This was requested via https://community.okteto.com/t/third-party-crds-in-okteto-cloud/196

Rename Gitlab > GitLab

Typo fix across documentation. Rename "Gitlab" > "GitLab"

document how to use a custom pipeline image

Minimum required: git, bash and openssh-client + whatever includes alpine:latest by default

FROM alpine:latest

RUN apk update && apk add --no-cache git bash openssh-client

Rethink the `Okteto Build` section

The Okteto Build section is oriented on how okteto build worked in the Okteto CLI v1. Today, okteto build behavior is defined in the okteto manifest.

I would focus this section on the advantages of building images in the cluster (as resuing cache layers between users), add links to https://www.okteto.com/docs/cloud/build/ and https://www.okteto.com/docs/reference/cli/#build, and maybe elaborate on the differences between building in a vanilla cluster, and building in a cluster managed by okteto.

Another option is to combine this section with the Okteto Registry

Custom 404 error page for documentation instead of Netlify's default 404 page

404s for the documentation displays the default Netlify page, that even links to Netlify's documentation:

We should create a custom Okteto 404 page.

Document sanitization for Build, Dev and Global Forward sections

after adding okteto/okteto#3021 we need to let know the user this behavior. First we need to wait to integrate global forwards docs.

Better explanation in using-dev-envs.mdx

I think it should be explicitly mentioned in the Development Environments page that only the docker compose file is being used in the Movies App with Docker Compose section and not the Okteto manifest file and the reason for this should be mentioned too.

In the Movies App with Helm section, it should be mentioned that a helm chart is being used alongside the manifest file in the deploy section of the manifest.

I as a first time visitor think that these changes would help first time users understand the docs better.

Document DigitalOcean volume limitation

Currently, there is a limitation with Digital Ocean and out autoscaler regarding the volumes configuration https://www.okteto.com/docs/self-hosted/administration/configuration/#autoscaler.

The problem is that we cannot get properly the maximum number of volumes allowed per node. This is an important value used by the autoscaler to know when it has to scale up and scale down. Also, it is important because Digital Ocean has a limitation of only 7 attached volumes per node https://docs.digitalocean.com/products/volumes/details/limits/ and this is a low number.

We can document in the Digital Ocean installation guide and in the autoscaler setting this specific case and recommend to set the following configuration:

  volumes.up: 6
  volumes.down: 5

Automate docs version generation

When a new Okteto self-hosted version becomes available we need to automatically generate a new version of the docs alongside the release notes. We currently do it manually.

This is somewhat related to #176 and we could use this data as the source of truth and pick the last 6 versions automatically from there.

Migrate samples, tutorials and getting started guides to the new `okteto dev` experience

Once the Okteto Dev spec is implemented, our samples should have an okteto manifest that says how to build your container image, how to deploy your application, and how to develop in one component. For example, for the hello world samples, it would look like this:

build:
   hello-world: .
deploy:
   - kubectl apply -f k8s.yml
 devs:
    hello-world:
      image: okteto/golang:1
      sync:
        - .:/app
      forward:
        - 2345:2345

Document that `wait` on dependencies waits until everything is healthy

For dependencies, we are not documenting:

The default value of wait
That we wait until all the services in the dependency are healthy