okteto / docs Goto Github PK

License: Apache License 2.0

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

docs's Issues

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)

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.

convert tutorials to blogs + documentation pages

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

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....

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

Document how to use ResourceEphemeralStorage

okteto/okteto#2902

@maroshii maybe we can collaborate with Dan on a blog post (or video) on how/why to use them? It could be cool way to showcase our community.

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

"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?

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 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.

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 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

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

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

Rename Gitlab > GitLab

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

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.

Sample for working with `npm link`

Document "publicOverride"

The user needs to create its own ingress/certificate, and then configure publicOverride in the okteto chart

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

Use Okteto preview environments for PR reviews

It'd be nice to use https://www.okteto.com/docs/cloud/preview-environments/preview-environments-github/ to have preview environments on each PR

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.

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

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

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 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

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

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.

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

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

"How to" optimize Dockerfiles with Buildkit series

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 `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

Update `build` section to explain limitations of vanilla clusters

Explain the limitations of the okteto build flags in the build cli section.

These flags can only be used if the user is building a single image, and they overwrite the value in the okteto manifest

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)

Create doc for Cloud new network quotas

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.

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

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 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

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 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.

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!").

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

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

okteto / docs Goto Github PK

docs's Issues

Small enhancements

Suggestions

Recommend Projects

Recommend Topics

Recommend Org