diff --git a/README.md b/README.md index e47e4e77b..2a8a6d54f 100644 --- a/README.md +++ b/README.md @@ -33,7 +33,56 @@ yarn run docusaurus docs:version 0.XX This will create a new version with the docs on your current branch. Do this before you start merging the docs for the next version. -After this, modify [`docusaurus.config.js`](docusaurus.config.js) to add the version to the dropdown. We typically keep the last 6 versions in the dropdown. +Modify the `presets.docs.versions` section of [`docusaurus.config.js`](docusaurus.config.js) as follows: + + +1. Update `lastVersion` to the new official version + +2. Update `current` to the version in development + +3. Update the values of the `path` of the previous official version in the `versions` subsection to match the version number. + + Before + ``` + '1.4': { + label: '1.4', + path: '/' + banner: 'none', + }, + ``` + + After + ``` + '1.4': { + label: '1.4', + path: '1.4' + banner: 'none', + }, + ``` + +4. Add a new entry in the `versions` subsection to match the new official version, with `/` as the path. + + ``` + '1.5': { + label: '1.5', + path: '/' + banner: 'none', + }, + ``` + + +Modify the redirection rules on `netlify.toml` so that `/docs/$OFFICIAL_VERSION/` redirects to `/docs` + +``` +# Redirect the current version to /docs/ +[[redirects]] + from = "/docs/1.5/*" + to = "/docs/:splat" + status = 301 +``` + +https://github.com/okteto/docs/pull/314 is a good example of how to set up the files + ## Components diff --git a/docusaurus.config.js b/docusaurus.config.js index de6dc7ca4..728e9016e 100644 --- a/docusaurus.config.js +++ b/docusaurus.config.js @@ -153,15 +153,20 @@ module.exports = { routeBasePath: '/', breadcrumbs: false, sidebarPath: require.resolve('./sidebars.js'), - lastVersion: '1.4', + lastVersion: '1.5', versions: { current: { + label: '1.6', + path: '1.6', + }, + '1.5': { label: '1.5', - path: '1.5', + path: '/', + banner: 'none', }, '1.4': { label: '1.4', - path: '/', + path: '1.4', banner: 'none', }, '1.3': { diff --git a/netlify.toml b/netlify.toml index 1d67b7768..1e5d16e7e 100644 --- a/netlify.toml +++ b/netlify.toml @@ -8,6 +8,12 @@ to = "/docs/self-hosted/:splat" status = 301 +# Redirect the current version to /docs/ +[[redirects]] + from = "/docs/1.5/*" + to = "/docs/:splat" + status = 301 + # Before version 1.4, we used to point the homepage to `/welcome/overview`. # These redirects make sure we don’t show a 404 @@ -16,11 +22,6 @@ to = "/docs/" status = 301 -[[redirects]] - from = "/docs/1.4/welcome/overview/" - to = "/docs/" - status = 301 - [[redirects]] from = "/docs/1.3/welcome/overview/" to = "/docs/1.3" @@ -65,11 +66,6 @@ from = "/docs/0.11/welcome/overview/" to = "/docs/0.11" status = 301 - -[[redirects]] - from = "/docs/1.4/*" - to = "/docs/:splat" - status = 301 [[redirects]] from = "/*" diff --git a/okteto.yml b/okteto.yml index 1c64b3442..708d26621 100644 --- a/okteto.yml +++ b/okteto.yml @@ -1,25 +1,10 @@ name: docs -# The build section defines how to build the images of your development environment -# More info: https://www.okteto.com/docs/reference/manifest/#build build: docs: context: . -# The deploy section defines how to deploy your development environment -# More info: https://www.okteto.com/docs/reference/manifest/#deploy -deploy: - commands: - - name: Deploy - command: echo 'Replace this line with the proper 'helm' or 'kubectl' commands to deploy your development environment' - -# The dependencies section defines other git repositories to be deployed as part of your development environment -# More info: https://www.okteto.com/docs/reference/manifest/#dependencies -# dependencies: -# - https://github.com/okteto/sample -# The dev section defines how to activate a development container -# More info: https://www.okteto.com/docs/reference/manifest/#dev dev: docs: image: ${OKTETO_BUILD_DOCS_IMAGE} diff --git a/versioned_docs/version-1.5/administration/cleanup.mdx b/versioned_docs/version-1.5/administration/cleanup.mdx new file mode 100644 index 000000000..be8af0e44 --- /dev/null +++ b/versioned_docs/version-1.5/administration/cleanup.mdx @@ -0,0 +1,69 @@ +--- +title: Resource Cleanup +description: Okteto saves resources by putting to sleep idle applications and cleaning up unused namespaces. +sidebar_label: Resource Cleanup +id: cleanup +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TiersList from '@theme/TiersList'; + +## Sleeping resources + +To automatically save resources in your cluster, you can configure Okteto to automatically scale inactive applications and resources to zero if they haven't been used for longer than the `inactivity` period. + +## Inactive Applications and Resources + +Okteto considers an application or resources inactive if a user hasn't performed any of the following tasks during the `inactivity` period: + +- Upgrade or redeploy via the UI or the command line. +- Launched a development container with `okteto up`. +- Pushed the latest version of your code with `okteto push`. + +Service accounts, config maps, secrets, or volumes you create will be unaffected by this operation. + +## Wake sleeping resources + +Okteto's UI will notify you when there are sleeping resources in your namespace. Press the **Wake all** button to activate all sleeping resources at once. + +

wake a sleeping resource

+ +Sleeping resources are also started if anyone visits any of the public endpoints of your application. + +## Delete Unused Namespaces + +Namespaces and all the resources and data contained within will be deleted if they are not used for longer than the `deletion` period. + +## Persistent resources + +In case you are interested on the garbage collector but you want to skip some specific namespace, you can mark it as `persistent`. To do so, you can add the label `dev.okteto.com/persistent` to it or [use the admin view](administration/dashboard.mdx#namespaces-section). + +In case you want more granularity and only want to persist specific deployments or statefulsets within a namespace, you can include the label `dev.okteto.com/persistent` on those resources. In that case, the garbage collector will ignore only those specific resources while scaling down the rest of the namespace. + + +## Configuration Steps + +You can consult the `deletion` and `inactivity` periods in the [Admin Dashboard](administration/dashboard.mdx). + + + + +You can enable and customize the `inactivity` and `deletion` periods via the [garbage collector's settings](self-hosted/administration/configuration.mdx#gc). + + + + + +If your instance is hosted by Okteto, [reach out to support](https://okteto.com/support) to modify this configuration. + + + + diff --git a/versioned_docs/version-1.5/administration/dashboard.mdx b/versioned_docs/version-1.5/administration/dashboard.mdx new file mode 100644 index 000000000..15eb99fe9 --- /dev/null +++ b/versioned_docs/version-1.5/administration/dashboard.mdx @@ -0,0 +1,97 @@ +--- +title: Admin Dashboard +description: Admin Dashboard +id: dashboard +--- + +import TiersList from '@theme/TiersList'; + +# Admin Dashboard + +The Admin Dashboard provides a web UI for administering some features of Okteto. + +You can access the Admin Dashboard by clicking on the `Admin` icon on the left sidebar. + +## Accessing the dashboard + +Only accounts with the administrator role will be able to access the Administration Dashboard. The first user signing up into your Okteto instance will automatically become the initial administrator. + +You can promote other accounts to the administrator role in the `Users` section of the Admin Dashboard or by adding the `dev.okteto.com/super: "true"` label to the corresponding `serviceAccount` in Kubernetes. + +## Overview Section + +The overview section of the Admin Dashboard shows you the following information: + +- Expiration date of your license +- Number of available seats +- Number of nodes in your cluster +- Number of namespaces managed by Okteto +- Number of preview environments currently active +- Autoscaler configuration +- Garbage Collector configuration + +## Users Section + +You can administer all users in your Okteto instance from the Admin Dashboard's Users section. + +For each user, an administrator will be able to: + +- View their name, email, and avatar +- Change their role +- Remove the user + +> Removing the user will automatically remove all the namespaces owned by the deleted user. + +## Nodes Section + +The Nodes section of the Admin Dashboard provides the following system information about your Kubernetes cluster: + +- Number of running pods +- Total amount of memory currently in use +- Total amount of memory requested +- Total amount of CPU currently in use +- Total amount of CPU requested + +You can use this information to configure [the autoscaler](self-hosted/administration/configuration.mdx#autoscaler). + +## Namespaces Section + +You can administer all namespaces in your Okteto instance from the Admin Dashboard's Namespaces section. + +For each namespace, an administrator will be able to: + +- View the name, owner, resources currently consumed, resources presently requested, and the last time it was accessed +- Mark the namespace as `persistent` to prevent it from being automatically scaled to zero or deleted by the [garbage collector](administration/cleanup.mdx#delete-unused-namespaces) +- Get `read-only` access to any namespace managed by Okteto + +## Secrets Section + +The Secrets section of the Admin dashboard lets you define cluster-wide secrets. Using the `$SECRET_NAME` syntax, you can refer to these secrets directly in your Okteto manifest. They are also injected into the [environment running](cloud/okteto-cli.mdx#built-in-tools-when-deploying-to-okteto-cloud) the commands in the `deploy` section of the manifest. + +> Secrets [defined by the user](cloud/secrets.mdx) take precedence over the secrets defined here in case of a name collision. + +We recommend using [build secrets](reference/manifest.mdx#build-object-optional) to inject sensitive data into your Dockerfile. + +The example below shows how to configure your okteto manifest to mount a local `.env` file into your Dockerfile: + +```yaml +build: + api: + context: . + secrets: + my_env: .env +``` + +You can refer to this secret from your Dockerfile using the syntax below: + +``` +RUN --mount=type=secret,id=my_env,dst=/etc/secrets/.env cat /etc/secrets/.env +``` + +The content of the `.env` file would be: + +``` +${MY_PASSWORD} +``` + +where `MY_PASSWORD` can be a local environment variable or an Okteto Secret, and it gets subsituted by Okteto before mounting the file as a build secret. diff --git a/versioned_docs/version-1.5/administration/gitcatalog.mdx b/versioned_docs/version-1.5/administration/gitcatalog.mdx new file mode 100644 index 000000000..28576a3f8 --- /dev/null +++ b/versioned_docs/version-1.5/administration/gitcatalog.mdx @@ -0,0 +1,69 @@ +--- +title: Git Catalog +description: Administrators can create a catalog of pre-defined development environments for developers to use. +sidebar_label: Git Catalog +id: git-catalog +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TiersList from '@theme/TiersList'; + +# Git Catalog + +The Git Catalog feature enables `admins` to pre-configure a list of repositories, from the Okteto web UI, that are made available to `developers` in the same Okteto instance when they launch a dev environment from the UI. By pre-configuring these catalog entries, a developer can shorten the time it takes to deploy a development environment. With Git Catalog, developers don’t need to worry about using the right Okteto manifest or configuring the necessary environment variables. + +This feature gives more control to Okteto administrators over the developer experience and provides a more seamless workflow to help developers get started with their work. + +## Create your git catalog + +:::info + +*Only accounts with the administrator role can use this feature.* + +::: + +Within the Okteto UI, navigate to the `Admin` page and select the `Catalog` tab. On this tab, click the `Add Repository` button to open the `Add Repository` form. + +### Add a repository to the catalog + +Completing this form adds an entry to your Git Catalog, which is basically a pre-defined repository configuration that enables a developer to one-click deploy a development environment using that repository and the definition you’ve provided for it. + +Fill out as much of the form that makes sense for you. You will see: + +- Name* +- Repository URL* +- [Default Branch](#define-a-default-branch) +- [Manifest Path](#define-a-manifest-path) +- [Environment Variables](#add-environment-variables) + +Only the `Name` and `Repository URL` fields are required. When done, click `Save`. + +

add a git catalog repository

+ +### Define a Default Branch + +The default branch you specify here will be the default branch used when a developer selects this Git Catalog item to deploy a development environment. + +You can specify multiple catalog entries for the same `Repository URL` and set a different `Default Branch` for each one if your use case necessitates that. + +### Define a Manifest Path + +This field should (optionally) point to where your Okteto manifest resides. This provides additional control to provide a smoother experience for developers who deploy a development environment from the Git Catalog. + +### Add Environment Variables + +You can also (optionally) add Environment Variables to your Git Catalog entry to standardize how the development environment is deployed. Similar to the Default Branch entry, you could specify multiple catalog entries for the same Repository URL each with different Environment Variables. + +

add environment variables to git catalog repo

+ +## Launch a Dev Environment from your Git Catalog + +Once you’ve defined your Git Catalog entries, you can navigate to `Namespaces` → `Launch Dev Environment` → `Catalog`. + +In this tab you should see all of the repositories you’ve added (and pre-configured). Select an entry you wish to use and click `Launch`. + +

launch a git catalog development environment

+ +

view a git catalog repo's environment variables

\ No newline at end of file diff --git a/versioned_docs/version-1.5/administration/images/gc_add_env_vars.png b/versioned_docs/version-1.5/administration/images/gc_add_env_vars.png new file mode 100644 index 000000000..e62142c93 Binary files /dev/null and b/versioned_docs/version-1.5/administration/images/gc_add_env_vars.png differ diff --git a/versioned_docs/version-1.5/administration/images/gc_add_repo.png b/versioned_docs/version-1.5/administration/images/gc_add_repo.png new file mode 100644 index 000000000..b63e5a1dd Binary files /dev/null and b/versioned_docs/version-1.5/administration/images/gc_add_repo.png differ diff --git a/versioned_docs/version-1.5/administration/images/gc_launch_dev_env.png b/versioned_docs/version-1.5/administration/images/gc_launch_dev_env.png new file mode 100644 index 000000000..49eee10c6 Binary files /dev/null and b/versioned_docs/version-1.5/administration/images/gc_launch_dev_env.png differ diff --git a/versioned_docs/version-1.5/administration/images/gc_view_env_vars.png b/versioned_docs/version-1.5/administration/images/gc_view_env_vars.png new file mode 100644 index 000000000..827a91856 Binary files /dev/null and b/versioned_docs/version-1.5/administration/images/gc_view_env_vars.png differ diff --git a/versioned_docs/version-1.5/administration/images/wake.png b/versioned_docs/version-1.5/administration/images/wake.png new file mode 100644 index 000000000..dbc679826 Binary files /dev/null and b/versioned_docs/version-1.5/administration/images/wake.png differ diff --git a/versioned_docs/version-1.5/administration/private-repositories/github.mdx b/versioned_docs/version-1.5/administration/private-repositories/github.mdx new file mode 100644 index 000000000..8f472862e --- /dev/null +++ b/versioned_docs/version-1.5/administration/private-repositories/github.mdx @@ -0,0 +1,37 @@ +--- +title: GitHub +description: Use our GitHub Integration so your users can access private repositories in their development environments +sidebar_label: GitHub +id: github-app +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TiersList from '@theme/TiersList'; + +You can configure Okteto to use a GitHub to authenticate your users as well as give them access to private GitHub repositories. + +There are several reasons for considering this approach including: +- Your users can select a repo from a list, instead of having to type the full repository URL. +- Give everyone on your cluster read-only access to private repositories. +- Control access to Okteto and the repositories at the Organization level, or per repository. +- The pipelines use an app-scoped token, instead of a shared user. + + +## Adding or removing private repositories + +You can update or revoke the permissions over your private repositories or organizations by going to the `Integrations` tab in the `Settings` page of your Okteto instance. + +

update private repositories

+ +Click on the `Configure GitHub` button to add or remove repositories. This will open a configuration dialog from GitHub. From there, you'll be able to add or remove repositories from any organization you belong to. + +

add repositories to Okteto

+ +If you select repositories from a different organization (or user account) than the one you used to create the GitHub Application, GitHub will prompt you to install the application in the GitHub organization. Only organization administrators can complete this action. + +## GitHub org administrators + +If you're an administrator, you can grant team members access to your organization's repositories. Please note, even if you grant Okteto permission to all of your organization's repositories, each developer will only have access to those repositories that they are able to access through GitHub. This allows you to maintain security, and ensure that only those authorized to access code may do so. + diff --git a/versioned_docs/version-1.5/administration/private-repositories/images/private-repositories-enable.png b/versioned_docs/version-1.5/administration/private-repositories/images/private-repositories-enable.png new file mode 100644 index 000000000..5c055e89c Binary files /dev/null and b/versioned_docs/version-1.5/administration/private-repositories/images/private-repositories-enable.png differ diff --git a/versioned_docs/version-1.5/administration/private-repositories/images/private-repository-ssh-key.png b/versioned_docs/version-1.5/administration/private-repositories/images/private-repository-ssh-key.png new file mode 100644 index 000000000..b27a8a1f9 Binary files /dev/null and b/versioned_docs/version-1.5/administration/private-repositories/images/private-repository-ssh-key.png differ diff --git a/versioned_docs/version-1.5/administration/private-repositories/images/private-repository.png b/versioned_docs/version-1.5/administration/private-repositories/images/private-repository.png new file mode 100644 index 000000000..1ce9e3d54 Binary files /dev/null and b/versioned_docs/version-1.5/administration/private-repositories/images/private-repository.png differ diff --git a/versioned_docs/version-1.5/administration/private-repositories/images/wake.png b/versioned_docs/version-1.5/administration/private-repositories/images/wake.png new file mode 100644 index 000000000..dbc679826 Binary files /dev/null and b/versioned_docs/version-1.5/administration/private-repositories/images/wake.png differ diff --git a/versioned_docs/version-1.5/administration/private-repositories/ssh-key.mdx b/versioned_docs/version-1.5/administration/private-repositories/ssh-key.mdx new file mode 100644 index 000000000..496b97fd8 --- /dev/null +++ b/versioned_docs/version-1.5/administration/private-repositories/ssh-key.mdx @@ -0,0 +1,32 @@ +--- +title: Authenticating with an SSH Key +description: Use an SSH key so your users can access private repositories in their development environments +sidebar_label: SSH Key +id: ssh-key +--- + +import Image from '@theme/Image'; +import TiersList from '@theme/TiersList'; + +# Authenticating with an SSH Key + +Okteto generates an SSH key the first time it boots. This key is the identity used by Okteto when cloning repositories while executing a [git deployment pipeline](cloud/deploy-from-git.mdx). You can use this SSH key to give Okteto permission to clone private repositories. + +## Get your Public Key + +The public SSH is available on the `Settings` section on the `Admin -> General` page. Click on the `Show SSH Key` button to reveal the value. This will only be displayed for users with the `Admin` role. + +

show SSH key

+ +## Add the Public Key to your Source Code Provider +Once you have the public key, follow your source code provider's instructions on how to add the SSH key to your account. We recommend that you create a dedicated `bot` account for Okteto. + +- https://docs.github.com/en/github/authenticating-to-github/adding-a-new-ssh-key-to-your-github-account +- https://docs.gitlab.com/ee/ssh/ +- https://support.atlassian.com/bitbucket-cloud/docs/set-up-an-ssh-key/ + +## Deploy a Private Repository + +To deploy a private repository, use the `SSH` url of your git repository. This applies both when using the [`Deploy`](cloud/deploy-from-git.mdx) dialog in the dashboard and the [`okteto pipeline deploy`](reference/cli.mdx#deploy) command from your terminal. + +

add a private repository

\ No newline at end of file diff --git a/versioned_docs/version-1.5/api.mdx b/versioned_docs/version-1.5/api.mdx new file mode 100644 index 000000000..78c024fb6 --- /dev/null +++ b/versioned_docs/version-1.5/api.mdx @@ -0,0 +1,132 @@ +--- +title: Okteto GraphQL API +description: Reference of Okteto's GraphQL API +id: api +--- + +import Image from '@theme/Image'; + +> Public access to the GraphQL API is in beta, and it is subject to breaking changes without notice. + + +## The GraphQL API endpoint + +If you using Okteto Cloud, the endpoint is available at: +``` +https://cloud.okteto.com/graphql +``` + +For Okteto users, the endpoint will be available at: +``` +https://$YOUR_OKTETO_INSTANCE/graphql +``` + +The endpoint remains constant no matter what operation you perform. + +## Authentication + +To communicate with the GraphQL API, you'll need your Okteto API token. You can get to it by browsing to your Okteto instance and clicking on the `Settings` button on the left of the dashboard. + +

Screenshot of the Okteto app and API settings

+ +When making a GraphQL request, you always need to include your token as a bearer token authentication header. + +## Making GraphQL Calls + +Because GraphQL operations consist of multiline JSON, we recommend using a GraphQL client when making the calls, such as [Postman](https://postman.com) or [Insomnia](https://insomnia.rest/). You can also use cURL or any other HTTP-speaking library. + +When using a REST api, http verbs determine the operation to perform. In GraphQL, you'll send a JSON body independently of the operation you're performing, so the http verb is always POST. The only exception is an introspection query, which is a GET to the endpoint, used to get information on the GraphQL endpoint. + +``` +curl -XPOST \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{"query": "query { user { email }}"}' \ + https://cloud.okteto.com/graphql +``` + +The full schema of our GraphQL API is available here. + +## Example Scenarios + +### Create Namespace + +Request body: +``` +mutation{ + createSpace(name: "api-cindy", members:""){ + id + } +} +``` + +Parameters: +- name: The name of the namespace. +- members: List of emails of the members of the space. Using this to share it with your team (optional). + + +The `createSpace` mutation is idempotent. If you execute it on a namespace that already exists, it will update the member list. + +### Delete Namespace + +Request body: +``` +mutation{ + deleteSpace(id: "api-cindy"){ + id + } +} +``` + +Parameters: +- name: The name of the namespace. + +Danger! Use this API with extreme care, as *it will delete everything in the namespace*, including your volumes. Don't say we didn't warn you. + +### Deploy Helm Application + +Request body: + +``` +mutation { + deployApp( + version: "0.1.0", + config: "bW9uZ29kYjoKICBtb25nb2RiUGFzc3dvcmQ6ICJQYXNzd29yZCExQDIiIA==" + name: "my-instance", + space: "cindy" + repo: "https://apps.okteto.com", + chart: "movies" + ){ + name + } +} +``` + +Parameters: +- chart: The name of the application +- repo: The URL of the application repository +- name: The name of your application instance, must be unique +- space: The name of the namespace to deploy into +- version: The version to deploy +- config: The base64 encoded configuration of your application + +The `deployApp` mutation is idempotent. If you execute it on an application that already exists, it will upgrade the application. + +### Destroy Helm Application + +Request body: + +``` +mutation { + deployApp( + space: "cindy" + name: "my-instance", + ) { + name + } +} +``` + +Parameters: +- space: The namespace to use +- name: The name of your application instance, must be unique diff --git a/versioned_docs/version-1.5/cloud/build.mdx b/versioned_docs/version-1.5/cloud/build.mdx new file mode 100644 index 000000000..9f2bf9d45 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/build.mdx @@ -0,0 +1,30 @@ +--- +title: Okteto Build Service +description: The Okteto Build service allows you to build your development images directly in the Okteto Cloud infrastructure +sidebar_label: Build Service +id: build +--- + +import Image from '@theme/Image'; + +The Okteto Build service allows you to build your development images directly in the Okteto Cloud infrastructure. Another reason to remove Docker and Kubernetes from your laptop and develop directly in Okteto Cloud. + +## Build images + +You'll need the [okteto CLI](cloud/okteto-cli.mdx) in order to access the Okteto Build Service. + +Once the Okteto CLI is installed, run `okteto context` and select the Okteto Cloud option to download the credentials and certificates required to access the Okteto Build service. + +After that, run the `okteto build` command to build and push your images. + +``` +okteto build -t okteto.dev/hello-world:golang . +``` + +You can build and push images to any available docker registry. If you're not using the Okteto Registry, the `okteto build` command will use your available `docker` registry credentials. + +[Refer to this document](reference/cli.mdx#build) for more information on the `okteto build` command. + +## Quotas + +Access to the Okteto Registry is included with all Okteto Cloud accounts. Developer accounts get 15 builds per day for free. diff --git a/versioned_docs/version-1.5/cloud/credentials.mdx b/versioned_docs/version-1.5/cloud/credentials.mdx new file mode 100644 index 000000000..ea3914482 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/credentials.mdx @@ -0,0 +1,109 @@ +--- +title: Download your Kubernetes credentials +description: Download your Kubernetes credentials and start developing your applications in Okteto Cloud +sidebar_label: Kubernetes Credentials +id: credentials +--- + +import Image from '@theme/Image'; +import Button from '@theme/Button'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Download your Kubernetes credentials and start developing your applications in Okteto Cloud with your favorite CLI tools. +There are two different ways of downloading your Kubernetes credentials: + +- Download your Kubernetes credentials [using the Okteto CLI](#download-your-kubernetes-credentials-using-the-okteto-cli). + +- Download your Kubernetes credentials [from the Okteto Cloud UI](#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Download your Kubernetes credentials using the Okteto CLI + +If this is your first time using the Okteto CLI, install it following [this guide](cloud/okteto-cli.mdx). + +The Okteto CLI can download your Kubernetes credentials from Okteto Cloud. To do this, run the `okteto context` command: + +```console +$ okteto context use https://cloud.okteto.com +``` + +```console +Authentication will continue in your default browser + ✓ Context 'cloud.okteto.com' created +``` + +If you're not logged into Okteto Cloud yet, it will also run the login sequence. + +Once your okteto context is configured to access Okteto Cloud, run the following command: + +```console +$ okteto kubeconfig +``` + +```console +Updated kubernetes context 'cloud_okteto_com/cindy' in '/Users/cindy/.kube/config' +``` + +The `okteto kubeconfig` command adds your Kubernetes credentials to your kubeconfig file, and sets it as the current Kubernetes context. +Once you do this, you'll have full access to your Kubernetes namespace with `kubectl`, `helm` or any other CLI tool. + +## Download your Kubernetes credentials from the Okteto Cloud UI + +Download your Kubernetes credentials and save them in a well-known location: + +

+ +

+ +From the Okteto Cloud UI you should also find your credentials in the `Settings > Setup` section. + +Once downloaded, point your `KUBECONFIG` environment variable to the credentials file: + + + + +```console +$ export KUBECONFIG=$HOME/Downloads/okteto-kube.config:${KUBECONFIG:-$HOME/.kube/config} +``` + + + + + +```console +> $Env:KUBECONFIG=("$HOME\Downloads\okteto-kube.config;$Env:KUBECONFIG;$HOME\.kube\config") +``` + + + + + +To see that the new configuration is working, enter this command: + +```console +$ kubectl get all +``` +```console +No resources found. +``` + +## Using your Kubernetes credentials + +Once you've downloaded your credentials, you'll have full access to your Kubernetes namespaces on Okteto Cloud directly from your terminal, using the tools you're already familiar with, such as `helm`, `kubectl`, `okteto` or `skaffold`. + +For example, you could use `kubectl` to deploy our `hello-world` application: + +```terminal +kubectl apply -f https://raw.githubusercontent.com/okteto/go-getting-started/master/k8s.yml +``` + +[Okteto Cloud](index.md) is a multi-tenant environment. A combination of RBAC, pod security policies, resource quotas, network policies, admission controllers, and custom code are put in place to ensure that Okteto Cloud namespaces are isolated, secure, and easy to use for everyone. +Take a look at the [FAQs](reference/faqs.mdx) to understand the limitations and restrictions most likely to affect your applications in Okteto Cloud. diff --git a/versioned_docs/version-1.5/cloud/custom-domains.mdx b/versioned_docs/version-1.5/cloud/custom-domains.mdx new file mode 100644 index 000000000..eaf10cd02 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/custom-domains.mdx @@ -0,0 +1,218 @@ +--- +title: Custom Domain Names for your Applications +description: Use a custom domain name for your applications +sidebar_label: Custom Domain Names +id: custom-domains +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TiersList from '@theme/TiersList'; + +# Custom Domain Names for your Applications + +By default, an application deployed in Okteto will be available at its Okteto subdomain, which has the form `*-.`. + +For example, an application called `hello` deployed in the namespace `cindylopez` will be available at `https://hello-cindylopez.cloud.okteto.net` on Okteto Cloud. + +To make your applications available on a non-Okteto subdomain (for example: `myapp.com`), you can add a **custom domain to your Okteto namespace**. + +Applications that use custom domains will automatically get issued a valid certificate, just like regular Okteto endpoints. + +> Okteto does not provide a domain registration service (for registering a custom domain name) or a DNS provider service. + +## Add a Custom Domain Name to your Application. + +Perform the following tasks to use your custom domain in an Okteto Namespace: + + + + +1. Update your DNS configuration so your custom domain points to the [Okteto subdomain](cloud/custom-domains.mdx#configure-your-dns). + +2. Execute the following commands in the namespace you are configuring with custom domains: + +``` +kubectl label ns dev.okteto.com/custom-domain=true --overwrite +kubectl annotate ns $ns dev.okteto.com/domain= --overwrite +``` + +and create the following `Issuer` in your namespace: + +``` +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: okteto-http01 +spec: + acme: + server: https://acme-v02.api.letsencrypt.org/directory + email: + preferredChain: "" + privateKeySecretRef: + name: okteto-http01 + solvers: + - http01: + ingress: + class: nginx + serviceType: ClusterIP +``` + + + + +1. Install cert-manager in your cluster. + +2. Update your DNS configuration so your custom domain points to the [Okteto subdomain](cloud/custom-domains.mdx#configure-your-dns). + +3. Execute the following commands in the namespace you are configuring with custom domains: + +``` +kubectl label ns dev.okteto.com/custom-domain=true --overwrite +kubectl annotate ns $ns dev.okteto.com/domain= --overwrite +``` + +and create the following `Issuer` in your namespace: + +``` +apiVersion: cert-manager.io/v1 +kind: Issuer +metadata: + name: okteto-http01 +spec: + acme: + server: https://acme-v02.api.letsencrypt.org/directory + email: + preferredChain: "" + privateKeySecretRef: + name: okteto-http01 + solvers: + - http01: + ingress: + class: nginx + serviceType: ClusterIP +``` + + + + +## Configure your Application to use your Custom Domain + +Once your domain has been registered with Okteto, it's time to put it to use. + +If you're using Okteto's [auto-ingress](cloud/ssl.mdx) or [generate the host](cloud/ssl.mdx#let-okteto-generate-the-host) features, then there's nothing to change. Just redeploy your application, and it will automatically pick up your custom domain. + +For example, if your application's endpoint was `https://hello-cindylopez.cloud.okteto.net` and you added the custom domain `myapp.com`, after redeployment your application's endpoint will be `https://hello.myapp.com`. + +### Using your Root Domain + +If you want to make your application available in the root domain you provided, you'll need to make a small change to your manifests. + +If you're using Okteto's auto-ingress features, change the value of the `dev.okteto.com/auto-ingress` annotation in your service to the word `domain`, as shown below: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hello-service + annotations: + dev.okteto.com/auto-ingress: "domain" +spec: + type: ClusterIP + ports: + - name: "hello-world" + port: 8080 + selector: + app: hello-world +``` + +If you're creating your own ingress, change the value of the `dev.okteto.com/generate-host` annotation in your ingress to the word `domain`, as shown below: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: hello-ingress + annotations: + dev.okteto.com/generate-host: "domain" +spec: + rules: + - http: + paths: + - backend: + serviceName: hello-world + servicePort: 8080 +``` + +If you deployment is powered by Docker Compose, add a label to the service you want to configure a custom domain as shown below: + +```yaml +services: + fastapi: + build: . + replicas: 1 + ports: + - 8080:8080 + environment: + - DB_HOST=postgres://pguser:pgpass@postgres:5432/pgdb + - secret=dev + labels: + dev.okteto.com/auto-ingress: "domain" + postgresql: + image: bitnami/postgresql:latest + ports: + - 5432 + environment: + - POSTGRES_USER=pguser + - POSTGRES_PASSWORD=pgpass + - POSTGRES_DB=pgdb + volumes: + - data:/bitnami/postgresql +volumes: + data: + +``` + +Okteto will automatically generate the correct host at deploy time. For example, if you added the custom domain `myapp.com` to your namespace, the ingress will be created with `myapp.com` as the host. + +```console +$ kubectl get ingress custom-dns +``` + +``` +NAME HOSTS ADDRESS PORTS AGE +custom-dns myapp.com 104.155.138.215,104.197.238.82,104.198.241.5,35.224.92.98 80, 443 169m +``` + +We recommend you use this approach instead of hardcoding the hostname in your manifests to keep them portable across namespaces. + +## Configure your DNS + +In order to use your custom domain in Okteto, you'll need to point your custom DNS to `.`. + +You usually configure a `CNAME` record with your DNS provider to point to it. We recommend you add a wildcard entry so you don't need to create an entry for every service deployed: + +| Record | Name | Target | +| ------------- |:-------------:| :-----:| +| `CNAME` | `*.myapp.com` | `cindylopez.cloud.okteto.net` | +| `CNAME` | `myapp.com` | `cindylopez.cloud.okteto.net` | + +> Consult your DNS provider's documentation for specific instructions on creating CNAME records. + +You can confirm your DNS is configured correctly with the `host` command, assuming your DNS changes have propagated: + +``` +$ host hello.myapp.com +``` + +``` +hello.myapp.com is an alias for cindylopez.cloud.okteto.net. +cindylopez.cloud.okteto.net has address ... +``` diff --git a/versioned_docs/version-1.5/cloud/deploy-from-git.mdx b/versioned_docs/version-1.5/cloud/deploy-from-git.mdx new file mode 100644 index 000000000..c821a9113 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/deploy-from-git.mdx @@ -0,0 +1,121 @@ +--- +title: Deploy your Development Environments from your Git Repositories +description: Deploy your development environments directly from your Git repositories +sidebar_label: From Git Repositories +id: deploy-from-git +--- + +import Image from '@theme/Image'; + + + +## Prerequisites + +Please make sure to configure your Git repositories with the [appropriate manifests](cloud/okteto-cli.mdx#deployment-manifests) before using them to launch Dev Environments. + +## Deploy + +Log in to [Okteto Cloud](https://cloud.okteto.com), and click on the **Launch Dev Environment** button on the top left. +A dialog will open asking for a Git repository to deploy. Make sure that "**Git URL**" is selected as the source. +Type the URL for the Movies App repo (https://github.com/okteto/movies), pick a branch, and click **Launch**: + +

deploy from git

+ +When you launch a dev environment using a Git repository, Okteto Cloud will analyze your repo and automatically deploy it running `okteto deploy --build`. +In the example above, Okteto will install the chart of the Movies App with Helm. + +> Check the [Okteto Manifest](reference/manifest.mdx) to learn more about how to configure your development environment deployment with an `okteto.yml` file. + +As soon as your development environment is deployed, you'll see its state in the UI. The UI will be automatically updated as the different components are created. +Your development environment will be ready to go once it reaches the `Success` state. + +

UI of the movies app

+ +## Redeploy + +Click the **Redeploy** button on the right of your development environment. + +A dialog will open where you can modify the branch to redeploy: + +

Redeploy in git

+ +Click **Deploy** and your development environment will be updated with the source code of the given branch. + +## Destroy + +You can also destroy your development environment with a single click. + +Go back to the extended menu of your development environment and click the **Destroy** button. +A confirmation dialog will pop up. Click on **Destroy** and your development environment and all of the resources created for it will be gone: + +

Destroy application

+ +You won't be able to recover resources after the development environment has been destroyed, so back up any sensitive data before running this action. + +## Variables + +When you deploy from Git, you can add Variables that will be available as environment variables during the deployment of your development environment. + +## Adding a Develop on Okteto Button + +The **Develop on Okteto** button is a shortcut to deploy your development environments with a single click. + +The button is designed to be used in GitHub README files, documentation sites, or pretty much anywhere that renders an HTML file. +Use this instead of writing a never-ending list of manual steps on how to deploy your development environments. + +Here's an example button that deploys [the Movies App](https://github.com/okteto/movies) on Okteto Cloud. + +[![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://cloud.okteto.com/#/deploy?repository=https://github.com/okteto/movies) + +### Adding the Develop on Okteto button + +There are two ways of referencing the source code repository: +- Resolve it implicitly. This is useful in GitHub `README.` files. If you don't specify the repository, Okteto will infer it using the `referer` header. This only works on public repositories hosted in https://github.com. +- Using the `repository` and `branch` parameters. This is useful for buttons hosted outside of https://github.com, in blog posts, or documentation. + +#### Using an implicit repository + +If you're embedding the button in a public GitHub repository's `README` file, Okteto will automatically infer the repository and the branch using the referer header when someone clicks on the button. + +Here's an example: + +```markdown +[![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://cloud.okteto.com/deploy) +``` + +And here's the equivalent content as HTML if you prefer that: + +```html + + Develop on Okteto + +``` + +A `develop-okteto.png` is also available. + +#### Adding explicit parameters + +Use the following Markdown snippet as a template, changing the `repository` and `branch` query parameters to match your repository. The `branch` query parameter is optional. + +```markdown +[![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://cloud.okteto.com/deploy?repository=https://github.com/okteto/movies&branch=main) +``` + +And here's the equivalent content as HTML if you prefer that: + +```html + + Develop on Okteto + +``` + +### Parameters + +You can parametrize your development environment deployment using the following parameters: + +- `repository`: The repository to be deployed. If it's not present, Okteto will automatically infer it using the referer header, if available. +- `branch`: The repository branch to be deployed. If not included, it will use the default branch of the repository. +- `vars`: It allows you to specify a list of variables that will be available as environment variables during the deployment. It is optional. .e.g `vars=[{"name":"THEME","value":"dark"},{"name":"LANG","value":"en"}]`. This would generate 2 environment variables avaible on your deployment: `THEME=dark` and `LANG=en`. It has to be URL encoded. +- `filename`: The location of the [Okteto Manifest](reference/manifest.mdx) relative to the root of the repository. \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/deploy-from-helm.mdx b/versioned_docs/version-1.5/cloud/deploy-from-helm.mdx new file mode 100644 index 000000000..17a618685 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/deploy-from-helm.mdx @@ -0,0 +1,56 @@ +--- +title: Launch Applications from Helm Charts +description: You can launch additional services for your development environments directly from Helm Charts +sidebar_label: From Helm Charts +id: deploy-from-helm +--- + +import Image from '@theme/Image'; + +You can launch additional services for your development environments on Okteto Cloud using Helm repositories. +Okteto automates all the processes needed to deploy, configure, upgrade, and destroy your Helm releases, so you can focus on building amazing applications. + +## Add your own charts + +You can also list your own charts under the [Helm Catalog](self-hosted/administration/configuration.mdx#applications) tab of the **Launch Dev Environment** menu. +This would give you the same one-click deployment experience for your own services when using [Okteto Self-Hosted](self-hosted.mdx). + +## Deploy + +Log in to [Okteto Cloud](https://cloud.okteto.com), and click on the **Launch Dev Environment** button on the top left. A deploy dialog will open. +Switch to the *From Chart* tab and a list of available services to deploy on your namespace will be shown. +The list will look something like this: + +

deploy with helm

+ +Click on the service you want to deploy (we'll be using **Redis** in this example) to switch to the deployment configuration view of the Helm Chart. There you give it a name, select a version, and customize the configuration values. Once you're ready, click on the **Deploy** button on the bottom of the dialog to deploy your Helm release. + +

deploy redis

+ +When you click on **Launch**, Okteto Cloud will launch an installation job for you directly in the cluster. The installation job is in charge of executing the required `helm` commands to deploy your Helm Chart. + +As soon as your Helm release is deployed, you'll see its state in the UI. The UI will automatically update as the different components are created. Your Helm release will be ready to go once it reaches the `Success` state. + +

UI image of redis

+ +## Redeploy + +You can also redeploy your Helm releases from Okteto Cloud. This is useful when you want to upgrade or redeploy your services. + +Click on **Redeploy** on the right of your Helm release. +The *Redeploy Helm Chart* dialog shows you the available versions, as well as the configuration used to deploy the current version of the Helm release. + +

redeploy helm chart

+ +Select the version you want to deploy to, change the configuration if needed, then click on the **Redeploy** button to start the upgrade process. Just like when you installed the Helm release, all the changes will be reflected in your browser as they happen. + +## Destroy + +You can also destroy your Helm releases with a single click. +Go back to the extended view of your Helm release and click the **Destroy** button. +A confirmation dialog will pop up. Click on the **Destroy** button to confirm your actions. The Helm release and all the resources created for it will be gone: + +

Destroy Helm releases

+ +In this case, the persistent volume created by Redis won't be deleted to avoid losing any sensitive data. +You can delete it manually from the Okteto Cloud UI if you want. diff --git a/versioned_docs/version-1.5/cloud/deploy-from-terminal.mdx b/versioned_docs/version-1.5/cloud/deploy-from-terminal.mdx new file mode 100644 index 000000000..2d3f6ece7 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/deploy-from-terminal.mdx @@ -0,0 +1,30 @@ +--- +title: Deploy Applications from your Terminal +description: You can launch Kubernetes applications directly from your terminal +sidebar_label: From Your Terminal +id: deploy-from-terminal +--- + +import Image from '@theme/Image'; + +You have full access to your Kubernetes namespaces on Okteto Cloud directly from your terminal, using the tools you're already familiar with, such as `helm`, `kubectl`, `okteto` or `skaffold`. + +## Download your Kubernetes credentials + +In order to access your namespaces from your terminal, download your Kubernetes credentials from Okteto Cloud. +[This document](cloud/credentials.mdx) will walk you through the necessary steps for this. + +You can also use the `okteto kubeconfig` command to download your Kubernetes credentials. This will let you interact with your Okteto Namespaces using Kubernetes-native tools like `kubectl` or `helm`. + +## Deploy your Application + +Once the credentials have been configured, deploy your applications using your favorite CLI tool. +For example, you could use `kubectl` to deploy our `hello-world` application: + +```terminal +kubectl apply -f https://raw.githubusercontent.com/okteto/go-getting-started/master/k8s.yml +``` + +Okteto Cloud is a multi-tenant environment. +A combination of RBAC, pod security policies, resource quotas, network policies, admission controllers, and custom code is put in-place to ensure that Okteto Cloud namespaces are isolated, secure, and easy to use for everyone. +[Take a look at this document](cloud/multitenancy.mdx) to understand the limitations and restrictions most likely to affect your applications in Okteto Cloud. diff --git a/versioned_docs/version-1.5/cloud/develop-on-okteto-button.mdx b/versioned_docs/version-1.5/cloud/develop-on-okteto-button.mdx new file mode 100644 index 000000000..7f02646dd --- /dev/null +++ b/versioned_docs/version-1.5/cloud/develop-on-okteto-button.mdx @@ -0,0 +1,75 @@ +--- +title: Develop On Okteto Button +description: Deploy your development environments from your Git repositories +sidebar_label: Adding A Develop On Okteto Button +id: develop-on-okteto-button +--- + +import Image from '@theme/Image'; + +The **Develop on Okteto** button is a shortcut to deploy your development environments with a single click. + +The button is designed to be used in Git `README` files, documentation sites, or pretty much anywhere that renders an html file. +Use this instead of writing a never-ending list of manual steps on how to deploy your development environments. + +Here's an example button that deploys [the Movies App](https://github.com/okteto/movies) on Okteto Cloud. + +[![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://cloud.okteto.com/#/deploy?repository=https://github.com/okteto/movies) + + +### Requirements + +The basic requirements for creating the button are that your application can be deployed in Okteto Cloud, and that the application's source code is hosted in a public Git repository. + +The easiest way to validate this is to follow the instructions in the [Deploy from Git](cloud/deploy-from-git.mdx) document. + +### Adding the Develop on Okteto button + +There are two ways of referencing the source code repository: +- Resolve it implicitly. This is useful in GitHub `README.` files. If you don't specify the repository, Okteto will infer it using the `referer` header. This only works on public repositories hosted in https://github.com. +- Using the `repository` and `branch` parameters. This is useful for buttons hosted outside of https://github.com, in blog posts or documentation. + +#### Using an implicit repository + +If you're embedding the button in a public GitHub repository's `README` file, Okteto will automatically infer the repository and the branch using the referer header when someone clicks on the button. + +Here's an example: + +```markdown +[![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://cloud.okteto.com/deploy) +``` + +And here's the equivalent content as HTML if you prefer that: + +```html + + Develop on Okteto + +``` + +A `develop-okteto.png` is also available. + +#### Adding explicit parameters + +Use the following Markdown snippet as a template, changing the `repository` and `branch` query parameters to match your repository. The `branch` query parameter is optional. + +```markdown +[![Develop on Okteto](https://okteto.com/develop-okteto.svg)](https://cloud.okteto.com/deploy?repository=https://github.com/okteto/movies&branch=main) +``` + +And here's the equivalent content as HTML if you prefer that: + +```html + + Develop on Okteto + +``` + +### Parameters + +You can parametrize your deployment using the following parameters: + +- `repository`: The repository to be deployed. If it's not present, Okteto will automatically infer it using the referer header, if available. +- `branch`: The repository branch to be deployed. If not included, it will use the default branch of the repository. +- `vars`: It allows you to specify a list of variables that will be available as environment variables during the deployment. It is optional. .e.g `vars=[{"name":"THEME","value":"dark"},{"name":"LANG","value":"en"}]`. This would generate 2 environment variables avaible on your deployment: `THEME=dark` and `LANG=en`. It has to be URL encoded. +- `filename`: The location of the [Okteto manifest](reference/manifest.mdx) relative to the root of the repository. If not set, one of the [deployment related manifests](cloud/okteto-cli.mdx#deployment-manifests) will be used. diff --git a/versioned_docs/version-1.5/cloud/github-actions.mdx b/versioned_docs/version-1.5/cloud/github-actions.mdx new file mode 100644 index 000000000..0f70a13d6 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/github-actions.mdx @@ -0,0 +1,25 @@ +--- +title: GitHub Actions +description: Automate your development workflows using GitHub Actions and Okteto Cloud +sidebar_label: GitHub Actions +id: github-actions +--- + +Automate your development workflows using GitHub Actions and Okteto Cloud. + +GitHub Actions gives you the flexibility to build automated software development workflows. With GitHub Actions for Okteto Cloud, you can create workflows to build, deploy, and update your applications in Okteto Cloud. + +## Available Actions + +The GitHub Actions for Okteto Cloud are available directly from [the GitHub Markeplace](https://github.com/marketplace?type=actions&query=okteto). + +- [Activate Namespace](https://github.com/marketplace/actions/activate-namespace) +- [Build](https://github.com/marketplace/actions/okteto-build) +- [Context](https://github.com/marketplace/actions/okteto-context) +- [Create Namespace](https://github.com/marketplace/actions/create-namespace) +- [Delete Namespace](https://github.com/marketplace/actions/delete-namespace) +- [Deploy Pipeline](https://github.com/marketplace/actions/okteto-pipeline) +- [Destroy Pipeline](https://github.com/marketplace/actions/destroy-okteto-pipeline) +- [Deploy Preview](https://github.com/marketplace/actions/deploy-preview-environment) +- [Destroy Preview](https://github.com/marketplace/actions/destroy-preview-environment) + diff --git a/versioned_docs/version-1.5/cloud/images/add-secret.png b/versioned_docs/version-1.5/cloud/images/add-secret.png new file mode 100644 index 000000000..2815c420a Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/add-secret.png differ diff --git a/versioned_docs/version-1.5/cloud/images/delete-secret.png b/versioned_docs/version-1.5/cloud/images/delete-secret.png new file mode 100644 index 000000000..c6a58f176 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/delete-secret.png differ diff --git a/versioned_docs/version-1.5/cloud/images/deploy-git.png b/versioned_docs/version-1.5/cloud/images/deploy-git.png new file mode 100644 index 000000000..9ef2f37fa Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/deploy-git.png differ diff --git a/versioned_docs/version-1.5/cloud/images/deploy-helm.png b/versioned_docs/version-1.5/cloud/images/deploy-helm.png new file mode 100644 index 000000000..45693d9f1 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/deploy-helm.png differ diff --git a/versioned_docs/version-1.5/cloud/images/deploy-redis.png b/versioned_docs/version-1.5/cloud/images/deploy-redis.png new file mode 100644 index 000000000..e7b5ba71e Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/deploy-redis.png differ diff --git a/versioned_docs/version-1.5/cloud/images/destroy-git.png b/versioned_docs/version-1.5/cloud/images/destroy-git.png new file mode 100644 index 000000000..5f7ebc2d4 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/destroy-git.png differ diff --git a/versioned_docs/version-1.5/cloud/images/destroy-helm.png b/versioned_docs/version-1.5/cloud/images/destroy-helm.png new file mode 100644 index 000000000..6c52954f6 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/destroy-helm.png differ diff --git a/versioned_docs/version-1.5/cloud/images/github-pages.png b/versioned_docs/version-1.5/cloud/images/github-pages.png new file mode 100644 index 000000000..f9d227707 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/github-pages.png differ diff --git a/versioned_docs/version-1.5/cloud/images/hello-message.png b/versioned_docs/version-1.5/cloud/images/hello-message.png new file mode 100644 index 000000000..5dcb2563d Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/hello-message.png differ diff --git a/versioned_docs/version-1.5/cloud/images/hello-tom.png b/versioned_docs/version-1.5/cloud/images/hello-tom.png new file mode 100644 index 000000000..a6f90ad53 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/hello-tom.png differ diff --git a/versioned_docs/version-1.5/cloud/images/new-dialog.png b/versioned_docs/version-1.5/cloud/images/new-dialog.png new file mode 100644 index 000000000..7ad04ef9e Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/new-dialog.png differ diff --git a/versioned_docs/version-1.5/cloud/images/private-endpoints.png b/versioned_docs/version-1.5/cloud/images/private-endpoints.png new file mode 100644 index 000000000..cf7a83e80 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/private-endpoints.png differ diff --git a/versioned_docs/version-1.5/cloud/images/private-repositories-authorize.png b/versioned_docs/version-1.5/cloud/images/private-repositories-authorize.png new file mode 100644 index 000000000..1a10aed25 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/private-repositories-authorize.png differ diff --git a/versioned_docs/version-1.5/cloud/images/private-repositories-deploy.png b/versioned_docs/version-1.5/cloud/images/private-repositories-deploy.png new file mode 100644 index 000000000..649bbe2e6 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/private-repositories-deploy.png differ diff --git a/versioned_docs/version-1.5/cloud/images/private-repositories-enable.png b/versioned_docs/version-1.5/cloud/images/private-repositories-enable.png new file mode 100644 index 000000000..b5ebc844c Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/private-repositories-enable.png differ diff --git a/versioned_docs/version-1.5/cloud/images/private-repositories-list.png b/versioned_docs/version-1.5/cloud/images/private-repositories-list.png new file mode 100644 index 000000000..d75154a80 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/private-repositories-list.png differ diff --git a/versioned_docs/version-1.5/cloud/images/private-repositories-lock.png b/versioned_docs/version-1.5/cloud/images/private-repositories-lock.png new file mode 100644 index 000000000..f991d70ad Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/private-repositories-lock.png differ diff --git a/versioned_docs/version-1.5/cloud/images/private-repositories-update.png b/versioned_docs/version-1.5/cloud/images/private-repositories-update.png new file mode 100644 index 000000000..5922902d9 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/private-repositories-update.png differ diff --git a/versioned_docs/version-1.5/cloud/images/redeploy-git.png b/versioned_docs/version-1.5/cloud/images/redeploy-git.png new file mode 100644 index 000000000..1741e0e68 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/redeploy-git.png differ diff --git a/versioned_docs/version-1.5/cloud/images/redeploy-helm.png b/versioned_docs/version-1.5/cloud/images/redeploy-helm.png new file mode 100644 index 000000000..0d0b7d9c0 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/redeploy-helm.png differ diff --git a/versioned_docs/version-1.5/cloud/images/secrets.png b/versioned_docs/version-1.5/cloud/images/secrets.png new file mode 100644 index 000000000..069f8f732 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/secrets.png differ diff --git a/versioned_docs/version-1.5/cloud/images/share.png b/versioned_docs/version-1.5/cloud/images/share.png new file mode 100644 index 000000000..a045bf410 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/share.png differ diff --git a/versioned_docs/version-1.5/cloud/images/tokens-copy.png b/versioned_docs/version-1.5/cloud/images/tokens-copy.png new file mode 100644 index 000000000..a9f699e06 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/tokens-copy.png differ diff --git a/versioned_docs/version-1.5/cloud/images/tokens-delete-confirm.png b/versioned_docs/version-1.5/cloud/images/tokens-delete-confirm.png new file mode 100644 index 000000000..a677dca42 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/tokens-delete-confirm.png differ diff --git a/versioned_docs/version-1.5/cloud/images/tokens-delete.png b/versioned_docs/version-1.5/cloud/images/tokens-delete.png new file mode 100644 index 000000000..868a9e839 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/tokens-delete.png differ diff --git a/versioned_docs/version-1.5/cloud/images/tokens-name.png b/versioned_docs/version-1.5/cloud/images/tokens-name.png new file mode 100644 index 000000000..e727d26e2 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/tokens-name.png differ diff --git a/versioned_docs/version-1.5/cloud/images/tokens-new.png b/versioned_docs/version-1.5/cloud/images/tokens-new.png new file mode 100644 index 000000000..1db38ca1b Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/tokens-new.png differ diff --git a/versioned_docs/version-1.5/cloud/images/ui-movies-git.png b/versioned_docs/version-1.5/cloud/images/ui-movies-git.png new file mode 100644 index 000000000..4ceb36a07 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/ui-movies-git.png differ diff --git a/versioned_docs/version-1.5/cloud/images/ui-redis.png b/versioned_docs/version-1.5/cloud/images/ui-redis.png new file mode 100644 index 000000000..15e992670 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/ui-redis.png differ diff --git a/versioned_docs/version-1.5/cloud/images/ui.png b/versioned_docs/version-1.5/cloud/images/ui.png new file mode 100644 index 000000000..eab0578ae Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/ui.png differ diff --git a/versioned_docs/version-1.5/cloud/images/user-secret.png b/versioned_docs/version-1.5/cloud/images/user-secret.png new file mode 100644 index 000000000..276198f17 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/images/user-secret.png differ diff --git a/versioned_docs/version-1.5/cloud/multitenancy.mdx b/versioned_docs/version-1.5/cloud/multitenancy.mdx new file mode 100644 index 000000000..fab1be04d --- /dev/null +++ b/versioned_docs/version-1.5/cloud/multitenancy.mdx @@ -0,0 +1,186 @@ +--- +title: Default Settings for Okteto Cloud +description: Okteto Cloud gives you access to a Kubernetes namespace in a multi-tenant environment +sidebar_label: Default Settings +id: multitenancy +--- + +Okteto Cloud gives you access to a vanilla Kubernetes namespace in a multi-tenant environment. Okteto uses a combination of RBAC, pod security policies, resource quotas, network policies, admission controllers, and custom code to ensure that Okteto Cloud namespaces are isolated, secure, and easy to use for everyone. + +This document explains the limitations and restrictions most likely to affect your applications in Okteto Cloud. + +## Exposing services + +`NodePort` or `LoadBalancer` services are not supported in Okteto Cloud. Okteto Cloud automatically translates `NodePort` or `LoadBalancer` services into ingress rules. More information is [available here](cloud/ssl.mdx). + +## Pod Security Policies + +Okteto Cloud configures [pod security policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) to limit the privileges of your applications. The following options are not allowed: `privileged`, `hostNetwork`, `allowPrivilegeEscalation`, `hostPID`, `hostIPC`. Mounting volume host paths is also not allowed. + +## Resource quotas + +The following [resource quotas](https://kubernetes.io/docs/concepts/policy/resource-quotas/) are associated to every namespace created in Okteto Cloud: + + +| Resource | Quota | +|---|---| +| Namespaces | 5 | +| Pods | 10 | +| CPUs | 1CPU/pod with a maximum of 4CPUs/namespace | +| Memory | 3Gi/pod with a maximum of 8Gi/namespace | +| Storage | 5Gi | +| Services | 10 | +| Secrets | 50 | +| Config Maps | 50 | +| Persistent Volume Claims | 5 | + +## Network policies + +Okteto Cloud configures [network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) for each namespace. Only traffic between the pods running in your namespaces is allowed, as well as external traffic to the internet. + +## RBAC + +Okteto Cloud uses [RBAC rules](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to limit the access to the Kubernetes API. The supported endpoints are: + +```yaml +- apiGroups: + - "" + resources: + - pods + - pods/log + - pods/exec + - pods/attach + - pods/portforward + - configmaps + - secrets + - services + - endpoints + - serviceaccounts + - events + - persistentvolumeclaims + - replicationcontrollers + verbs: + - '*' +- apiGroups: + - "" + resources: + - events + - limitranges + - namespaces + - namespaces/status + - resourcequotas + - resourcequotas/status + verbs: + - get + - list +- apiGroups: + - metrics.k8s.io + resources: + - pods + verbs: + - get + - list +- apiGroups: + - autoscaling + resources: + - horizontalpodautoscalers + verbs: + - '*' +- apiGroups: + - apps + resources: + - daemonsets + - deployments + - replicasets + - statefulsets + verbs: + - '*' +- apiGroups: + - batch + resources: + - cronjobs + - jobs + verbs: + - '*' +- apiGroups: + - extensions + resources: + - deployments + - ingresses + - replicasets + verbs: + - '*' +- apiGroups: + - networking.k8s.io + resources: + - ingresses + verbs: + - '*' +- apiGroups: + - rbac.authorization.k8s.io + resources: + - roles + - rolebindings + verbs: + - '*' +- apiGroups: + - policy + resources: + - poddisruptionbudgets + verbs: + - '*' +- apiGroups: + - apiextensions.k8s.io + resources: + - customresourcedefinitions + verbs: + - list + - watch +- apiGroups: + - helm.fluxcd.io + resources: + - helmreleases + - helmreleases/status + verbs: + - '*' +- apiGroups: + - helm.integrations.flux.weave.works + resources: + - fluxhelmreleases + verbs: + - '*' +- apiGroups: + - configuration.konghq.com + resources: + - kongplugins + - kongconsumers + - kongcredentials + - kongingresses + - tcpingresses + verbs: + - '*' +- apiGroups: + - openfaas.com + resources: + - functions + verbs: + - '*' +- apiGroups: + - litmuschaos.io + resources: + - chaosengines + - chaosexperiments + - chaosresults + verbs: + - '*' +- apiGroups: + - cert-manager.io + resources: + - certificates + verbs: + - list + - watch + - get +``` + +You can only create `Roles` restricted to the endpoints above. `RoleBindings` can only refer to `Roles` existing on your namespaces. \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/namespaces.mdx b/versioned_docs/version-1.5/cloud/namespaces.mdx new file mode 100644 index 000000000..719511b48 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/namespaces.mdx @@ -0,0 +1,34 @@ +--- +title: Secure and isolated namespaces +description: Create and manage secure and isolated Kubernetes namespaces for you and your team +sidebar_label: Namespaces +id: namespaces +--- + +import Image from '@theme/Image'; + +With Okteto Cloud you can create and manage secure and isolated Kubernetes namespaces for you and your team. + +Okteto Cloud will take care of all the required RBAC roles and bindings, resources quotas and limits, pod security policies, and network policies so everyone in your team can safely deploy and develop applications in Kubernetes. + +## Manage your namespaces + +You can create up to five namespaces per account. Go to the [Okteto Cloud UI](https://cloud.okteto.com/#/?origin=docs) and click on the (+) symbol on the left. + +

new namespace dialog

+ +You can also create a namespace directly from the command line with the `okteto namespace create` command. + +Switch your kubectl configuration to point to your namespaces with the `okteto kubeconfig` command. + +Once you're done, you can also delete your namespace via the UI, or with the `okteto namespace delete` command. + +## Share your namespace + +By default, you'll be the only person with access to your namespaces. Invite your teammates to enable true real-time collaboration. + +To share a namespace go to the [Okteto Cloud UI](https://cloud.okteto.com/#/?origin=docs), select the namespace you want to share and press the `Share` button in the namespace menu (you'll find it in the main bar at the top). + +

share a namespace

+ +In the `Share` dialog, type the email address of the team members you want to share this namespace with. Once you press save, Okteto Cloud will update the necessary permissions and notify your teammates via email. \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/okteto-cli.mdx b/versioned_docs/version-1.5/cloud/okteto-cli.mdx new file mode 100644 index 000000000..9dbc5f2e8 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/okteto-cli.mdx @@ -0,0 +1,107 @@ +--- +title: Okteto CLI +description: Introduction to Okteto CLI +sidebar_label: Okteto CLI +id: okteto-cli +--- + +[Dev Environments](reference/development-environments.mdx) allow you to develop your deployed application locally. You continue coding in your favorite IDE and see the changes live on the deployed version of your application as soon as you hit save. Okteto CLI is an [open source](https://github.com/okteto/okteto) client-side only tool that allows you to launch Dev Environments in any Kubernetes cluster: your own, [Okteto Cloud](index.md), or [Okteto Self-Hosted](self-hosted.mdx). + +Learn more about the Okteto CLI + +- [Installation guide](getting-started.mdx#installing-okteto-cli) +- [Okteto CLI Reference](reference/cli.mdx) +- [File Synchronization](reference/file-synchronization.mdx) +- [SSH Server](reference/ssh-server.mdx) +- [FAQs](reference/faqs.mdx) +- [Known Issues](reference/known-issues.mdx) + + +## Deployment Manifests + +You need one of the following deployment manifests for your application so that Okteto CLI knows how to launch a Dev Environment for it. Okteto CLI will analyze your existing manifests (Helm, Kubernetes, etc.) and help you write an [Okteto Manifest](#okteto-manifest) for your application. It will then use this Okteto Manifest instead of your existing deployment manifests to spin up Dev Environments. + +If you're using a Docker Compose file, then Okteto CLI can directly launch a Dev Environment for your application without generating an Okteto Manifest. However, you can still choose to create the Okteto Manifest if you want more configuration over your environment. + +Okteto CLI will look for deployment manifests for your application in the following order: + +1. [Okteto Manifest](reference/manifest.mdx) file: if there is an `okteto.yml` or `.okteto/okteto.yml` file in your folder, Okteto will use this file to deploy your development environment. +1. [Docker Compose](reference/docker-compose.mdx) file: if there is an `okteto-compose.yaml` or `docker-compose.yaml` file, Okteto will use this file to deploy your development environment. +1. [Helm Chart](https://helm.sh/docs/topics/charts/): if there is a `chart`, `charts`, `helm/chart`, or `helm/charts` directory with a `Chart.yaml` file in it, Okteto will detect the chart and run `helm upgrade --install` on it to deploy your development environment. +1. [Kubernetes manifests](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/) folder: if there is a `manifests`, `kubernetes`, or `k8s` folder, Okteto will detect it and run `kubectl apply` to deploy your development environment. +1. [Kubernetes manifests](https://kubernetes.io/docs/concepts/cluster-administration/manage-deployment/) file: if there is a `manifests.yaml`, `kubernetes.yaml`, or `k8s.yaml` file, Okteto will detect it and run `kubectl apply` to deploy your development environment + +You can also explicitly define the location of the Okteto Manifest using the `-f` flag on any Okteto CLI command. + + +## Okteto manifest + +The Okteto manifest allows you to provide configuration for building, deploying, and developing your application in a Development Environment. This file is optional if you already have a Docker Compose file for your application. Learn more about the Okteto manifest [here](reference/manifest.mdx). + +### Sample Okteto Manifest + +```yaml +icon: https://apps.okteto.com/movies/icon.png +build: + api: + context: . +deploy: + - helm upgrade --install app chart --set image=${OKTETO_BUILD_API_IMAGE} +dev: + api: + command: ["bash"] + forward: + - 8080:8080 + - 9229:9229 + sync: + - .:/usr/src/app +``` + +This example shows how to `build` the container image of the **api** microservice, how to `deploy` the application using its helm chart, +and how to `dev`elop on the **api** microservice by synchronizing the local filesystem on the container path `/usr/src/app`. +If you want to learn more about what all you can configure in this manifest, head over to the [Okteto Manifest Reference](reference/manifest.mdx). + +### Built-in Environment Variables + +The installation job also populates the following environment variables. You can refer to this in your `deploy` commands if needed: +- `OKTETO_NAMESPACE`: the namespace where your application is going to be installed. +- `OKTETO_GIT_BRANCH`: the name of the Git branch currently being deployed. +- `OKTETO_GIT_COMMIT`: the SHA1 hash of the last commit of the branch. +- `OKTETO_REGISTRY_URL`: the url of the [Okteto Registry](cloud/registry.mdx). +- `BUILDKIT_HOST`: the address of the [Okteto Cloud buildkit instance](cloud/build.mdx). You can use it to build your images with any CLI tool that supports Buildkit builds. + +In order to refer to images in the `build` section of the Okteto Manifest, you can use the following environment variables: +- `${OKTETO_BUILD__IMAGE}`: the full image reference +- `${OKTETO_BUILD__REGISTRY}`: the registry URL where the image was pushed +- `${OKTETO_BUILD__REPOSITORY}`: the name of the image that was pushed +- `${OKTETO_BUILD__SHA}`: The latest tag and the SHA of the image + +For example, for the image `registry.cloud.okteto.net/cindy/hello-world:okteto`, you would have the following values: + +- `OKTETO_BUILD_HELLO_WORLD_IMAGE`: registry.cloud.okteto.net/cindy/hello-world@sha256:xxx +- `OKTETO_BUILD_HELLO_WORLD_REGISTRY`: registry.cloud.okteto.net +- `OKTETO_BUILD_HELLO_WORLD_REPOSITORY`: cindy/hello-world +- `OKTETO_BUILD_HELLO_WORLD_SHA`: okteto@sha256:xxx + +### Built-in Tools When Deploying To Okteto Cloud + +When launching a development environment [from a Git Repository](cloud/deploy-from-git.mdx), Okteto will run an installation job that clones the Git repository, checks out the selected branch, builds the images defined in the `build` section of your Okteto Manifest, and executes the sequence of `deploy` commands. The job will fail if any of the commands in the `deploy` list fails. +The installation job will run in a Debian Linux container with the following tools preinstalled: + +- `bash` +- `bazel` +- `cue` +- `curl` +- `envsubst` +- `git` +- `helm` +- `kubectl` +- `kustomize` +- `make` +- `okteto` +- `openssh` +- `wait-for-it` + +The installation job is automatically configured with your Okteto and Kubernetes credentials. + +> Are we missing any binaries you use? [Join our community and let us know!](https://community.okteto.com/c/feature-requests). diff --git a/versioned_docs/version-1.5/cloud/okteto-pipeline.mdx b/versioned_docs/version-1.5/cloud/okteto-pipeline.mdx new file mode 100644 index 000000000..01d3c4c05 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/okteto-pipeline.mdx @@ -0,0 +1,65 @@ +--- +title: Configure your Okteto Pipeline +description: How to Configure your own Okteto Pipeline +sidebar_label: Okteto Pipeline +id: okteto-pipeline +--- + +Okteto Pipelines allow you to configure how your [Git repositories](cloud/deploy-from-git.mdx) get deployed to [Okteto](index.md). You might want to use them if Okteto Cloud cannot detect how to deploy your application from your [deployment manifests](cloud/deploy-from-git.mdx#prerequisites) or simply when you want more control over how your application gets deployed. + +The Okteto Pipeline is executed relative to the path where the manifest is located. This means, if the manifest is at any subfolder, the pipeline will use the context of the subfolder where the manifest is defined. + +### Example okteto-pipeline.yml + +```yaml +icon: https://apps.okteto.com/movies/icon.png +deploy: + - okteto build -t okteto.dev/api:${OKTETO_GIT_COMMIT} api + - okteto build -t okteto.dev/frontend:${OKTETO_GIT_COMMIT} frontend + - helm upgrade --install movies chart --set tag=${OKTETO_GIT_COMMIT} +devs: + - api/okteto.yml + - frontend/okteto.yml +``` + +### Schema Reference + +- `icon`: the icon associated to your application in the Okteto Cloud Dashboard (optional). +- `deploy`: list of commands to deploy your application in your Kubernetes namespace. It is usually a combination of `helm`, `kubectl`, and `okteto` commands. +- `destroy`: list of commands to be executed when the pipeline is destroyed. It can be used to release any resource created outside Okteto. +- `devs`: the paths to the okteto manifests in your Git repository. This is used to fill the hints in the *Develop* dialog of each service (optional). + +For example, the above example builds fresh docker images for the api and frontend components of the [Movies App](https://github.com/okteto/movies), pushes these images to the [Okteto Registry](cloud/registry.mdx) and deploys the app with Helm. + +### Built-in tools + +Okteto will run an installation job that clones your Git repository, checks out the selected branch, and executes the sequence of `deploy` commands. The job will fail if any of the commands in the `deploy` list fails. + +The installation job will run in a Debian Linux container with the following tools preinstalled: + +- `bash` +- `bazel` +- `cue` +- `curl` +- `envsubst` +- `git` +- `helm` +- `kubectl` +- `kustomize` +- `make` +- `okteto` +- `openssh` +- `wait-for-it` + +The installation job container is automatically configured with credentials to use the above tools on the namespace where your application is deployed. + +> Are we missing any binaries you use? [Join our community and let us know!](https://community.okteto.com/c/feature-requests). + +### Built-in Environment Variables +The installation job also populates the following environment variables. You can refer to this in your `deploy` commands if needed: + +- `OKTETO_NAMESPACE`: the namespace where your application is going to be installed. +- `OKTETO_GIT_BRANCH`: the name of the Git branch currently being deployed. +- `OKTETO_GIT_COMMIT`: the SHA1 hash of the last commit of the branch. +- `OKTETO_REGISTRY_URL`: the url of the [Okteto Registry](cloud/registry.mdx). +- `BUILDKIT_HOST`: the address of the [Okteto Cloud buildkit instance](cloud/build.mdx). You can use it to build your images with any CLI tool that supports Buildkit builds. diff --git a/versioned_docs/version-1.5/cloud/permissions.mdx b/versioned_docs/version-1.5/cloud/permissions.mdx new file mode 100644 index 000000000..e29e11985 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/permissions.mdx @@ -0,0 +1,31 @@ +--- +title: GitHub Permissions for Okteto Cloud +description: Details of permissions requested by Okteto Cloud when you login using your GitHub account +sidebar_label: GitHub Permissions +id: permissions +--- + +import Image from '@theme/Image'; + +## GitHub Permissions + +When using the Okteto Cloud Dashboard to enable Preview Environments for your GitHub repositories, we request the following permissions: + +

permissions requested on github for preview environments

+ +The reasons for requesting the above permissions are listed below. + +### Repository Permissions + +- Contents: Needed to clone repositories for deploying Preview Environments +- Metadata: Needed to list repositories a user has access to on the Okteto Cloud Dashboard +- Pull Requests: Needed to comment on the pull requests with the deployed Preview Environment URL and to deploy/destroy a Preview Environment based on whether a PR has been opened/closed +- Commit Statuses: Needed to change the status of a commit to show if the Preview Environment for it was deployed successfully or not + +### Organization Permissions + +- Members: When an org admin installs Okteto Cloud for a GitHub organization, this permission allows us to list available repositories to all org members who log in to Okteto Cloud + +### User Permissions + +- Email Address: This is required during the sign up in order to link your GitHub account to your Okteto Cloud account. \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/personal-access-tokens.mdx b/versioned_docs/version-1.5/cloud/personal-access-tokens.mdx new file mode 100644 index 000000000..41ddaa1b8 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/personal-access-tokens.mdx @@ -0,0 +1,51 @@ +--- +title: Personal Access Tokens +description: Use Personal Access Tokens to Interact with the Okteto API +sidebar_label: Personal Access Tokens +id: personal-access-tokens +--- + +import Image from '@theme/Image'; + +You can use Personal Access Tokens instead of OAuth to authenticate with Okteto. + +Personal Access Tokens are useful when scripting, or when configuring [Preview Environments](cloud/preview-environments/overview.mdx). + +### Creating a Personal Access Token + +1. Sign in to your Okteto account. +1. Click on the **settings** icon on the left tab. +1. Click on the **New Token** button. +

new token

+1. Give your token a descriptive name and click the **Generate** button. +

token name

+1. Copy the token to your clipboard. For security reasons, after you navigate off the page, you will not see the token again. +

copy token to clipboard

+ +> Warning: Treat your tokens like passwords and keep them secret. Always use tokens as environment variables instead of hardcoding them into your programs. + +## Using a Token on the Command Line + +Once you have a token, you can use it to authenticate with the [Okteto CLI](reference/cli.mdx) instead of using your browser, as shown below: + +```console +$ okteto context use https://cloud.okteto.com --token $YOUR_TOKEN +``` + +Personal Access Tokens can also be used when setting the `OKTETO_TOKEN` environment variable. + +```console +$ export OKTETO_TOKEN=xxxxxxx +$ okteto namespace create test-cindylopez +``` + +### Revoking a Personal Access Token + +1. Sign in to your Okteto account. +1. Click on the **settings** icon on the left tab. +1. Click on the **Delete** button. +

delete a token

+1. Click on the **Delete Token** button to confirm that you want to delete your token. +

confirm token deletion

+ +Once deleted, the token is automatically revoked, and it can't be recovered. diff --git a/versioned_docs/version-1.5/cloud/preview-environments/dashboard.mdx b/versioned_docs/version-1.5/cloud/preview-environments/dashboard.mdx new file mode 100644 index 000000000..9b7a20027 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/preview-environments/dashboard.mdx @@ -0,0 +1,51 @@ +--- +title: Configuring Preview Environments +description: Create preview environments for your application using the Okteto Cloud Dashboard +sidebar_label: Configure +id: dashboard +--- + +import Image from '@theme/Image'; + + +There are two ways to configure [Preview Environments](cloud/preview-environments/overview.mdx) using Okteto Cloud for your GitHub repositories. This page will be covering the easier of the two methods, that is, using the Okteto Cloud Dashboard. If you want more control and configuration options for your Preview Environments, [GitHub Actions](cloud/preview-environments/github.mdx) are the way to go. Before proceeding with the steps here, please ensure you've gone through the [Prerequisites](cloud/preview-environments/overview.mdx#prerequisites) section. + +Note that this method is not applicable for users of [Okteto Self-Hosted](self-hosted.mdx) or Okteto for Teams. Please checkout [GitHub Actions](cloud/preview-environments/github.mdx) for configuring Preview Environments in those cases. + +### Step 1: Log into Okteto Cloud + +The first step is going to [Okteto Cloud](https://cloud.okteto.com/) and logging in. Once you log in, head over to the Preview Environments section using the sidebar menu. + +

preview env dashboard on okteto cloud

+ +In this guide, we will set up Preview Environments for a fork of the [movies-preview-environments](https://github.com/okteto/movies-preview-environments) repository. Head to that repository and [create a fork](https://docs.github.com/en/get-started/quickstart/fork-a-repo) of it under your GitHub account. Feel free to follow along with some other repository in your GitHub account once you've [configured](cloud/preview-environments/overview.mdx#prerequisites) it. + +### Step 2: Add Your Repository + +Click on the "Add a repository" button on the dashboard. If you're doing this for the first time, you'll have to install and authorize Okteto Cloud on the GitHub organization/account having the repository you want to configure the Preview Environments for. You can read more about what permissions Okteto Cloud requests and why over [here](cloud/permissions.mdx). + +

install and authorize Okteto Cloud on github account

+ +Please note that you can only install Okteto Cloud for repositories belonging to your own GitHub account. Only org admins can install Okteto Cloud in the case of repositories part of a GitHub organization. Non-admin users will have the option of sending a request to install Okteto Cloud to admins through GitHub. + +Once you do that, you should see your repository appear in the list. + +

list of repositories

+ +Select it and click the "Add" button. Additionally, you can also configure variables to configure your preview environment. These variables work just like the [built-in environment variables](cloud/okteto-cli.mdx#built-in-environment-variables). + +### Step 3: Make a Pull Request + +That's right, this was all the configuration you needed to do! Head over to your repository now and make a pull request. After you make a pull request, Okteto will add the application endpoints to it as a comment once the Preview Environment has been deployed. + +

endpoints for the pr

+ +Sharing this with team members is the best way to get their attention for reviews 😛 + +You should also be able to see the pull request details along with the endpoints on the Okteto Cloud Dashboard. + +

endpoints for the pr

+ +### Next Steps + +You've successfully configured Preview Environments for your GitHub repository and witnessed the magic of Okteto. However, this is only a part of what Okteto can do for your team's development workflow. You can take the next step towards enhancing your dev experience by looking at Okteto's [Development Environments](reference/development-environments.mdx). \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/preview-environments/github.mdx b/versioned_docs/version-1.5/cloud/preview-environments/github.mdx new file mode 100644 index 000000000..66cfc1e16 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/preview-environments/github.mdx @@ -0,0 +1,116 @@ +--- +title: Preview Environments Using GitHub Actions +description: Create a preview environment for your application using Okteto and GitHub Actions +sidebar_label: Using GitHub Actions +id: preview-environments-github +--- + +import Image from '@theme/Image'; + +This section will show you how to automatically create a preview environment for your applications using Okteto and GitHub Actions. + +## Pre-Requisites +- An Okteto account +- A [GitHub account](https://github.com) + +For this tutorial, we'll be using our sample [movies rental application](https://github.com/okteto/movies). If you're using your own application to follow along, please ensure you have your [Okteto Manifest](reference/manifest.mdx) configured. + +## Step 1: Create the GitHub Workflow + +To create the preview environments, we will use our [GitHub Actions for Okteto](https://github.com/okteto/actions). + +A preview environment follows the lifecycle of a Pull Request. The GitHub action we create will make sure that whenever a Pull Request is created: + +1. A preview environment is deployed in Okteto with the code in the PR +1. The PR is updated with the URL of the preview environment + +The sample repository has been configured to use [the workflow described above](https://github.com/okteto/movies/blob/main/.github/workflows/preview.yaml). +If you want to use this on for your repositories, all you need to do is to create a `.github/workflow` folder in the root of your repo, and save your workflow file in it. + +The workflow file to create the preview environments looks like this: + +```yaml +# file: .github/workflows/preview.yaml +on: + pull_request: + branches: + - main + +jobs: + preview: + runs-on: ubuntu-latest + steps: + - name: Context + uses: okteto/context@latest + with: + url: ${{secrets.OKTETO_URL}} + token: ${{ secrets.OKTETO_TOKEN }} + + - name: Deploy preview environment + uses: okteto/deploy-preview@latest + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + name: pr-${{ github.event.number }}-cindylopez + timeout: 15m +``` + +There are two different scopes for preview environments: +- `personal`, where the only one who has access to the environment is the logged user. +- `global`, where all cluster members have access to it and do not need to have the user's name at the end of the preview environment name. Only administrators cancreate a preview environment with global scope. + +> The `global` scope is not supported in Okteto Cloud + +## Step 2: Configure your secrets + +If you noticed, the workflow uses the `secrets.OKTETO_TOKEN` and `secrets.OKTETO_URL`. We do this, so we don't have to commit these values into our repo. + +Before you run this workflow you need to create the following secrets in your repository: + +- `OKTETO_TOKEN` with your personal access token as the value. +- `OKTETO_URL` with the URL of your Okteto instance (if left empty, it will default to https://cloud.okteto.com) + +[Follow the process in this guide to create a personal access token](https://okteto.com/docs/cloud/personal-access-tokens/). Once you've created the personal access token, add it to your GitHub repository following the instructions [here](https://docs.github.com/en/actions/security-guides/encrypted-secrets#creating-encrypted-secrets-for-a-repository). + +The workflow also uses `secrets.GITHUB_TOKEN`, but this gets populated automatically by GitHub. + +## Step 3: Open a Pull Request + +Once your changes are in your repository, go ahead and open a new pull request. GitHub will receive the event, and it will start your workflow. You can see the workflow's status and logs in the `checks` section of the pull request. + +

checks section of pull request

+ +## Step 4: See your changes live + +After a few seconds, the workflow will update the pull request with the URL of your preview environment. Click on it to see the changes in real-time. + +

preview environment message with URL

+ +Every time the branch is updated, the same workflow will run, automatically updating the preview environment. + +## Step 5: Cleanup + +The sample repo also includes a workflow [to cleanup the preview environments](https://github.com/okteto/movies/blob/main/.github/workflows/preview-closed.yaml) once the pull request is closed. We recommend you follow this pattern to remove the preview environment after merging a pull request automatically. + +```yaml +# file: .github/workflows/preview-closed.yaml +on: + pull_request: + types: + - closed + +jobs: + closed: + runs-on: ubuntu-latest + steps: + - name: Context + uses: okteto/context@latest + with: + url: ${{secrets.OKTETO_URL}} + token: ${{ secrets.OKTETO_TOKEN }} + + - name: Destroy preview environment + uses: okteto/destroy-preview@latest + with: + name: pr-${{ github.event.number }}-cindylopez +``` diff --git a/versioned_docs/version-1.5/cloud/preview-environments/gitlab.mdx b/versioned_docs/version-1.5/cloud/preview-environments/gitlab.mdx new file mode 100644 index 000000000..046ed6bfb --- /dev/null +++ b/versioned_docs/version-1.5/cloud/preview-environments/gitlab.mdx @@ -0,0 +1,150 @@ +--- +title: Preview Environments Using GitLab CI/CD +description: Create a preview environment for your application using Okteto and GitLab +sidebar_label: For GitLab +id: preview-environments-gitlab +--- + +import Image from '@theme/Image'; + +This section will show you how to automatically create a preview environment for your applications using Okteto and GitLab's review apps. + +## Pre-Requisites +- An Okteto account +- A [GitLab Account](https://gitlab.com) + +For this tutorial, we'll be using our sample [movies rental application](https://gitlab.com/okteto/preview-environments). If you're using your own application to follow along, please ensure you have your [Okteto Manifest](reference/manifest.mdx) configured. + +## Step 1: Configure your Okteto API Token + +To deploy a preview environment with Okteto, you need to define the following environment variables: + +1. `OKTETO_TOKEN`: an Okteto [personal access token](cloud/personal-access-tokens.mdx). +1. `OKTETO_USERNAME`: your Okteto username (in Okteto Cloud, this is your GitHub Username). +1. [Optional] `OKTETO_URL`: Specify the URL of your Okteto instance (e.g., https://okteto.dev.mycompany.com). If empty, it will default to https://cloud.okteto.com. + +To add the environment variables: + +1. Navigate to your GitLab repository. +1. Go to the **Settings** menu on the left, and click on the **CI/CD** entry. + +

GitLab settings, CI/CD

+1. Expand the **Variables** section, and click on the **Add Variable** button. +

GitLab settings, add variables

+ +1. Add *OKTETO_TOKEN* as the key, and your personal access token as the value, and press the *Add Variable* button. +

update variable with Okteto Token

+1. Repeat the same process to add the *OKTETO_USERNAME* and, optionally, the *OKTETO_URL* variables. +

environment variables added

+ +## Step 2: Configure the Preview Environment on the Repository + +To tell GitLab how to deploy our preview environment, you need to create a file named [`.gitlab-ci.yml`](https://docs.gitlab.com/ee/ci/yaml/gitlab_ci_yaml.html) file at the root of the repository. + +In this file, we'll define two jobs. The `review` creates a preview environment for every branch and a `stop-review` job to destroy it when merging or deleting the branch. + +The flow to create a preview environment looks like this: + +1. Create a dedicated namespace for the Preview Environment +1. Build and deploy the application using the [Okteto preview](cloud/preview-environments/overview.mdx) defined in the repository. +1. Add the URL of the Preview Environment to the Merge Request. + +The flow to delete a preview environment looks like this: + +1. Destroy the application deployed with the [Okteto preview](cloud/preview-environments/overview.mdx) + + +The `.gitlab-ci.yml` looks like this: + +```yaml +# file: .gitlab.ci.yml +image: okteto/okteto:2.4.2 + +stages: + - review + +review: + stage: review + variables: + APP: review-$CI_COMMIT_REF_SLUG + script: + - okteto preview deploy review-$CI_COMMIT_REF_SLUG-$OKTETO_USERNAME --scope personal --branch $CI_COMMIT_REF_NAME --repository $CI_REPOSITORY_URL --wait + + environment: + name: review/$CI_COMMIT_REF_SLUG + url: https://movies-review-$CI_COMMIT_REF_SLUG-$OKTETO_USERNAME.cloud.okteto.net + on_stop: stop-review + only: + - branches + except: + - master + +stop-review: + stage: review + when: manual + environment: + name: review/$CI_COMMIT_REF_SLUG + action: stop + script: + - okteto preview destroy review-$CI_COMMIT_REF_SLUG-$OKTETO_USERNAME + variables: + GIT_STRATEGY: none + only: + - branches + except: + - master +``` + +There are two scopes for preview environments, `personal`, where the only one who has access to the environment is the user, and `global`, where all cluster members have access to it and do not need to have the user's name at the end of the preview environment name. To create a preview environment with global scope it is necessary to have administrator permissions. + +A few recommendations when creating your preview environment: +- Create a preview environment per branch/merge request to keep things isolated. We use both `$CI_BUILD_REF_NAME` and `$OKTETO_USERNAME` in the name to ensure the namespace is unique and that we only create one per branch. +- Pass the URL of your preview environment using the `environment.url` key. That way, the reviewers can directly go to the preview environment from GitLab. +- Delete both the preview environment, and the namespace when the branch is deleted to cut down on manual deletion. + +> Learn more about [the okteto CLI here](reference/cli.mdx). + +## Step 3: Create a Merge Request + +Once your changes are in your repository, make a small code change and create a new merge request. + +After a few seconds, the workflow will update the pull request with the URL of your preview environment. Click on the *View App* button, access it, and see your changes running. + +

GitLab merge request

+ +## Step 4: Cleanup + +Merging the merge request or deleting the branch automatically triggers the `stop-review` job we defined in the `.gitlab-ci.yml` file. The `stop-review` job will destroy the preview environment automatically for you. + +## Configure your GitLab Runner in Okteto + +Okteto makes it easy to deploy your own [GitLab Runner](https://docs.gitlab.com/runner/) from the [Okteto Catalog](cloud/deploy-from-helm.mdx). Running your runners is useful if you find yourself constantly waiting for shared runners to be available or want to run more complex configurations. + +### Retrieve the Registration Information + +1. Navigate to your GitLab repository. +1. Go to the **Settings** menu on the left, and click on the **CI/CD** entry. +

settings for GitLab

+1. Expand the **Runners** section, and copy the URL and registration tokens. +

GitLab specific runners

+ +### Deploy your GitLab Runner + +1. Log in using your Okteto account. +1. Click on the **Deploy** button on the top. +1. Choose **Catalog** as the source, select **gitlab-runner** from the options below, and click **Deploy**. + +

GitLab deploy runner

+ +1. On the **configuration** section, add your runner registration token to the `runnerRegistrationToken` key. + +

GitLab deploy runner configuration

+ +1. [Optional] If you're running your own GitLab instance, also update the value of `gitlabUrl`. +1. Press the **Deploy** button. + +In a few seconds, your GitLab Runner will be deployed and registered with your repository. To validate this, go back to the **Runners** section on your repository's settings, and validate that the runner is available there. + +

GitLab runner registered

+ +> To learn more about GitLab Runners, we recommend you check [their official documentation](https://docs.gitlab.com/runner/). diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/auth-okteto-cloud.png b/versioned_docs/version-1.5/cloud/preview-environments/images/auth-okteto-cloud.png new file mode 100644 index 000000000..8d5b3916c Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/auth-okteto-cloud.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/check.png b/versioned_docs/version-1.5/cloud/preview-environments/images/check.png new file mode 100644 index 000000000..29969ca89 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/check.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner-configuration.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner-configuration.png new file mode 100644 index 000000000..ba3fbac87 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner-configuration.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner-registered.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner-registered.png new file mode 100644 index 000000000..50bda47fc Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner-registered.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner.png new file mode 100644 index 000000000..805782f48 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-deploy-runner.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-merge-request.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-merge-request.png new file mode 100644 index 000000000..9c4892069 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-merge-request.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables-added.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables-added.png new file mode 100644 index 000000000..d100c4acf Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables-added.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables-okteto-token.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables-okteto-token.png new file mode 100644 index 000000000..96ed37c67 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables-okteto-token.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables.png new file mode 100644 index 000000000..fa4e0ea20 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-add-variables.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-registration.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-registration.png new file mode 100644 index 000000000..545e80eb4 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd-registration.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd.png b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd.png new file mode 100644 index 000000000..3a92e9a64 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/gitlab-settings-cicd.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/message.png b/versioned_docs/version-1.5/cloud/preview-environments/images/message.png new file mode 100644 index 000000000..a5ff447dd Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/message.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/pr-endpoints.png b/versioned_docs/version-1.5/cloud/preview-environments/images/pr-endpoints.png new file mode 100644 index 000000000..7e21f1d63 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/pr-endpoints.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/pr-in-dashboard.png b/versioned_docs/version-1.5/cloud/preview-environments/images/pr-in-dashboard.png new file mode 100644 index 000000000..af4f32588 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/pr-in-dashboard.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/preview-env-dashboard-perms.png b/versioned_docs/version-1.5/cloud/preview-environments/images/preview-env-dashboard-perms.png new file mode 100644 index 000000000..0434d1ca9 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/preview-env-dashboard-perms.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/preview-env-dashboard.png b/versioned_docs/version-1.5/cloud/preview-environments/images/preview-env-dashboard.png new file mode 100644 index 000000000..4909f73a9 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/preview-env-dashboard.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/preview-environments.png b/versioned_docs/version-1.5/cloud/preview-environments/images/preview-environments.png new file mode 100644 index 000000000..1abeea092 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/preview-environments.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/images/repo-list.png b/versioned_docs/version-1.5/cloud/preview-environments/images/repo-list.png new file mode 100644 index 000000000..0fdc00e38 Binary files /dev/null and b/versioned_docs/version-1.5/cloud/preview-environments/images/repo-list.png differ diff --git a/versioned_docs/version-1.5/cloud/preview-environments/overview.mdx b/versioned_docs/version-1.5/cloud/preview-environments/overview.mdx new file mode 100644 index 000000000..fd020c49d --- /dev/null +++ b/versioned_docs/version-1.5/cloud/preview-environments/overview.mdx @@ -0,0 +1,25 @@ +--- +title: Preview Environments +description: Create a preview environment for your application using Okteto +sidebar_label: Overview +id: preview-environments +--- + +import Image from '@theme/Image'; + +Preview environments allow you to include a live preview of your changes on every pull request. This is a fantastic way to collaborate with your team's technical, as well as non-technical members, to receive early feedback. + +

Preview Environments

+ +Okteto's preview environments are powered by Kubernetes and easily integrate with your favorite source control and CI/CD provider. They work using the [Okteto manifest](cloud/okteto-cli.mdx#okteto-manifest), so are very simple to get started with. +You can use Preview Environments with either [Okteto Cloud](index.md) or with [Okteto Self-Hosted](self-hosted.mdx) if you want to run them on your Kubernetes infrastructure. + +- [GitHub](cloud/preview-environments/github.mdx) +- [GitLab](cloud/preview-environments/gitlab.mdx) +- Circle CI (coming soon!) +- Bitbucket Pipelines (coming soon!) +- CodeFresh (coming soon!) + +## Prerequisites + +Preview environments deploy the code in a pull request to [Okteto](index.md). You can configure the way your code gets deployed using the [Okteto manifest](cloud/okteto-cli.mdx#okteto-manifest)'s `deploy` section. diff --git a/versioned_docs/version-1.5/cloud/private-endpoints.mdx b/versioned_docs/version-1.5/cloud/private-endpoints.mdx new file mode 100644 index 000000000..6297a6a4f --- /dev/null +++ b/versioned_docs/version-1.5/cloud/private-endpoints.mdx @@ -0,0 +1,142 @@ +--- +title: Private Endpoints +description: Restrict access to your application's endpoints +sidebar_label: Private Endpoints +id: private-endpoints +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +Okteto Cloud allows you to restrict access to your application by marking its endpoints as private. Private endpoints can only be accessed by Okteto users who have access to your Okteto namespace, and they'll need to provide their credentials before being granted access. + +Private endpoints can be identified by the lock icon in the Okteto Cloud UI: + +

private endpoints UI

+ +## Enable Private Endpoints for your Application + + + + + +Add the annotation below to your service's manifest to make your application's endpoints private: + +``` + dev.okteto.com/auto-ingress: "private" +``` + +Using this annotation will tell Okteto to create a private http ingress rule for your application. + +Full example: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hello-world + labels: + app: hello-world + annotations: + dev.okteto.com/auto-ingress: "private" +spec: + type: ClusterIP + ports: + - port: 8080 + protocol: TCP + targetPort: 8080 + selector: + app: hello-world +``` + +> Private Endpoints generated this way follow the same rules and restrictions than [Automatic SSL Endpoints](cloud/ssl.mdx). + +### Advanced Scenarios + +You can also use this feature with your own ingresses. This is useful when you have more complex configurations, or when you only want to protect a subset of your application's endpoints. + +Add the annotation below to your ingress' manifest to make your application's endpoints private: + +``` + dev.okteto.com/private: "true" +``` + +Full example: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + annotations: + dev.okteto.com/private: "true" + name: hello-world +spec: + rules: + - http: + paths: + - backend: + serviceName: hello-world + servicePort: 8080 + path: / +``` + +If you only want to protect certain endpoints of you application (e.g the admin portal, or your metrics endopint), we recommend that you create two ingresses: +- A first ingress with the routes for all the public endpoints +- A second ingress, with the `dev.okteto.com/private` annotation, for all your private routes. + + + + + +Private Endpoints is one of the extensions that Okteto added to [Docker Compose](reference/docker-compose.mdx) to make it easier to develop cloud-native applications. + +You can enable private endpoints by adding the `dev.okteto.com/private: "true"` label to your service: + +```yaml +name: hello-world +services: + hello-world: + labels: + dev.okteto.com/private: "true" + image: nginx + ports: + - 8080:8080 +``` + +### Advanced Scenarios + +You can also define this at the `endpoint` level if needed. + +```yaml +name: hello-world +endpoints: + annotations: + dev.okteto.com/private: "true" + rules: + - path: / + service: hello-world + port: 8080 +services: + hello-world: + image: nginx + expose: + - 8080 +``` + + + + + +## Restrictions + +Private Endpoints use your Okteto Cloud account for authentication, so they're best suited to protect endpoints that you and your team will access via the browser. They're not recommended for automation, or to protect endpoints that will be accessed by your end users. + +Private Endpoints only restrict external access to your applications. Applications running in your namespace will be able to access your private endpoints without authentication by using the `service` name. \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/private-repositories.mdx b/versioned_docs/version-1.5/cloud/private-repositories.mdx new file mode 100644 index 000000000..5394c9233 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/private-repositories.mdx @@ -0,0 +1,45 @@ +--- +title: Private Repositories +description: Launch your development environments from your private Git repositories +sidebar_label: From Private Repositories +id: private-repositories +--- + +import Image from '@theme/Image'; + +## GitHub Private Repositories + +Okteto integrates with GitHub and allows you to easily deploy any repository from any account or organization you grant permissions to. You can connect both personal repositories and those belonging to an organization in the same Okteto account. + +### Grant permissions + +You'll need to perform the following steps the first time you grant GitHub permissions to Okteto: + +1. Log into Okteto Cloud +1. Click on the "**Launch Dev Environment**" button on the top +1. Make sure "**GitHub**" is the selected source +

Launch private repository from git

+ +1. Click on the **Configure GitHub** button, to open the authorization dialog from GitHub. GitHub will ask you to install the Okteto Cloud App in the accounts and organizations you select. Follow the instructions to grant permissions to your repositories. +

install Okteto Cloud

+ +1. Finally click on the **Install & Authorize** button to proceed. If you're not the administrator of the organization, GitHub will send an email notification to your administrator and wait for their authorization to complete the installation and grant you access. +

install and authorize repositories

+ +Once you or your administrator grants permission, Okteto will automatically list your private and public repositories in the **Launch** dialog. +

list of private repositories

+ +Private repositories will be identified by a "lock" icon. +

locked private repositories

+ +### Launch from a Private GitHub Repository + +After giving Okteto access to any of your public or private repositories, you'll be able to deploy from a GitHub repository [using an Okteto Manifest](cloud/okteto-cli.mdx#okteto-manifest). + +## Other Private Repositories + +You can also use `SSH` authentication to deploy a private repository. To do this, use the `SSH` url of your git repository. This applies both when using the [`Deploy`](cloud/deploy-from-git.mdx) dialog in the dashboard and the [`okteto pipeline deploy`](reference/cli.mdx#deploy) command from your terminal. + +

add a private repository

+ +[This document](administration/private-repositories/ssh-key.mdx) has more information on how to configure access to the private repository in your source code provider. diff --git a/versioned_docs/version-1.5/cloud/registry.mdx b/versioned_docs/version-1.5/cloud/registry.mdx new file mode 100644 index 000000000..9ca5ca242 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/registry.mdx @@ -0,0 +1,94 @@ +--- +title: Okteto Registry +description: The Okteto Registry allows every Okteto namespace to have its own space to store its container images +sidebar_label: Container Registry +id: registry +--- + +The Okteto Registry allows every Okteto namespace to have its own space to store its container images. + +## Authentication + +You can use [Okteto CLI](cloud/okteto-cli.mdx) to build and push images to the Okteto Registry. + +Run [`okteto context`](reference/cli.mdx#context) to configure Okteto CLI to be able to push images. This command will download the required tokens and certificates required to push and pull images to the Okteto Registry. + +## Push images into the Okteto Registry + +The Okteto CLI is automatically configured to interact with the Okteto Registry. Just make sure that you're using the registry URL with your Okteto namespace. + +```console +okteto build -t okteto.dev/hello-world:golang . +``` + +When using the Okteto CLI, you can use the notation `okteto.dev` to refer to images in your [Namespace](cloud/namespaces.mdx). `okteto.dev` gets expanded to `registry.cloud.okteto.net/`. For example, `okteto.dev/hello-world:golang` expands to `registry.cloud.okteto.net/cindy/hello-world:golang` for the namespace `cindy` and expands to `registry.cloud.okteto.net/tom/hello-world:golang` for the namespace `tom`. You can configure your current namespace using [Okteto CLI](cloud/okteto-cli.mdx)'s [`okteto namespace`](reference/cli.mdx#namespace) command. + +You can also use `okteto.dev` in your Dockerfiles when building using the [Okteto CLI](cloud/okteto-cli.mdx). + +``` +# Dockerfile +FROM okteto.dev/hello-world:golang +WORKDIR /app +COPY main.go ./ +RUN go build -o /usr/local/bin/hello-world +EXPOSE 8080 +CMD ["/usr/local/bin/hello-world"] +``` + +However, please note that this would not work if you try to build using `docker build` instead. In that case, you'll need to use the full expanded URL for your images. + +When using the expanded URL for the Okteto Registry, please make sure that your image names follow the following scheme, where `` is a valid Okteto [Namespace](cloud/namespaces.mdx). + +``` +registry.cloud.okteto.net//: +``` + +## Use images from the Okteto Registry + +Any image pushed into the Okteto Registry is private. You'll need to authenticate with the registry before pulling an image. + +Namespaces in Okteto Cloud are automatically allowed to pull images that belong to their namespace automatically. If your application uses images from the Okteto Registry, it'll be able to pull container images without any extra configuration. + +To pull an image from a different namespace, you'll need to create and configure the required `imagePullSecrets` as outlined [here](reference/faqs.mdx#how-to-use-private-images). + +## Push helm chart into the Okteto Registry + +Just as you can push images to the Okteto Registry, you also have the option to push Helm charts. To do this, the first step is to log in to the registry where you want to push the chart. For this you will need some credentials that you can obtain by executing the `okteto context show` command. This command will show you information about the current okteto context in use. + +``` +{ + "name": "https://cloud.okteto.com", + "id": "3cf4529c-1gbd-4364-99cf-3f4bbe499adb", + "username": "CindyLopez", + "token": "i3kDEh4FKqrJzY7e7Qamd8CfTTrjkPOTN5ftHoKl", + "namespace": "cindy-namespace", + "builder": "tcp://buildkit.cloud.okteto.net:1234", + "registry": "registry.cloud.okteto.net", + "personalNamespace": "cindylopez", + "isOkteto": true +} +``` + +You can retrieve your username, password (token), and the domain for your registry from the output. Using the [deploy section](https://www.okteto.com/docs/reference/cli/#deploy) of the manifest, you can use these values using the `OKTETO_USERNAME`, `OKTETO_TOKEN`, `OKTETO_NAMESPACE` and `OKTETO_REGISTRY` environment variables since Okteto will resolve their values for you. If the commands are not executed through the manifest, then you must define the values for these environment variables. + +``` +helm registry login ${OKTETO_REGISTRY} -u ${OKTETO_USERNAME} -p ${OKTETO_TOKEN} +``` + +Once you are logged in you will need to package the chart. + +``` +helm package ./chart +``` + +After that you can push the packaged Helm chart to the registry. + +``` +helm push ./movies-api-0.1.0.tgz oci://${OKTETO_REGISTRY}/${OKTETO_NAMESPACE} +``` + +Once the packaged chart has been pushed to the Okteto Registry, you can pull it by using the command below: + +``` +helm pull oci://${OKTETO_REGISTRY}/${OKTETO_NAMESPACE}/movies-api --version 0.1.0 +``` \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/secrets.mdx b/versioned_docs/version-1.5/cloud/secrets.mdx new file mode 100644 index 000000000..9a9a7e7b1 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/secrets.mdx @@ -0,0 +1,32 @@ +--- +title: Okteto Secrets +description: Okteto Secrets allows you to save application configuration in Okteto Cloud, and automatically inject them during deployment time +sidebar_label: Okteto Secrets +id: secrets +--- + +import Image from '@theme/Image'; + +Application configuration should be passed at deployment time, not hardcoded in your code. + +Okteto Secrets allows you to save application configuration in Okteto Cloud, and automatically inject it during deployment time. + +## Manage Okteto Secrets from the Okteto Cloud UI + +You can create and delete your Okteto Secrets from the `Secrets` tab in the `Settings` view of the Okteto Cloud UI: + +

Secrets in settings

+ +To create a new secret, click on the **Add Secret** button, and provide a name and a value. The value will be masked once the secret is created. + +

add a secret

+ +To delete an existing secret, click on the **Delete** button on the right. You'll have to confirm your choice before the secret is deleted. Deleted secrets can't be recovered, so be careful when doing this. + +

delete a secret

+ +## Accessing Okteto Secrets from your Okteto Pipeline + +Okteto Secrets are automatically injected in your [Okteto CLI](cloud/okteto-cli.mdx) commands as environment variables. + +Follow [this tutorial](https://github.com/okteto/pipeline-with-generated-secrets) for a sample using Okteto Secrets in an Okteto Pipeline. diff --git a/versioned_docs/version-1.5/cloud/sleeping.mdx b/versioned_docs/version-1.5/cloud/sleeping.mdx new file mode 100644 index 000000000..244be3980 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/sleeping.mdx @@ -0,0 +1,29 @@ +--- +title: Free Starter Plan +description: Okteto's free Starter plan is ideal for day to day development of cloud applications. +sidebar_label: Starter Plan +id: starter-plan +--- + +## Sleeping Applications in the Starter Plan + +As part of the [free **Starter** plan](https://www.okteto.com/pricing/?plan=SaaS) and in order to automatically save resources, inactive applications are automatically scaled to zero after 24 hours of inactivity. + +An application is considered inactive if you haven't performed any of the following things in the last 24 hours: + +- Upgrade or Redeploy it via the UI or the command line +- Launched a Developer Environment with okteto up +- Pushed the latest version of your code with okteto push + +Any service accounts, config maps, secrets, or volumes you create will be unaffected by this operation. + +Namespaces will be deleted after 15 days of inactivity. + +### Restart sleeping applications + +Wake your application by doing any of the following actions: + +- Visit any of the public endpoints of your application +- Press the **Wake All** button from the namespace view of the Okteto UI + +Upgrade to [one of our paid plans](https://www.okteto.com/pricing/?plan=SaaS) and get complete control of your team's development experience, including when your development environments go to sleep. diff --git a/versioned_docs/version-1.5/cloud/ssl.mdx b/versioned_docs/version-1.5/cloud/ssl.mdx new file mode 100644 index 000000000..c8b7e0eca --- /dev/null +++ b/versioned_docs/version-1.5/cloud/ssl.mdx @@ -0,0 +1,74 @@ +--- +title: Automatic SSL Endpoints +description: Automatically create an SSL endpoint for your deployments +sidebar_label: Automatic SSL +id: ssl +--- + +Okteto Cloud can automatically create an SSL endpoint for your deployments. In order to take advantage of this feature, add the annotation below to your service's manifest: + +``` + dev.okteto.com/auto-ingress: "true" +``` + +For example: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hello-world + labels: + app: hello-world + annotations: + dev.okteto.com/auto-ingress: "true" +spec: + type: ClusterIP + ports: + - port: 8080 + protocol: TCP + targetPort: 8080 + selector: + app: hello-world +``` + +> A sample of how this should look [is available here](https://github.com/okteto/go-getting-started/blob/master/k8s.yml#L26). + +Adding this annotation will tell Okteto to automatically create an https ingress rule for you that redirects to the first http port of your service. `NodePort` or `LoadBalancer` services are managed as if they had this annotation too. + +You can see the address of your endpoint by going to Okteto Cloud's UI. The endpoint address will be consistent across redeploys, as long as you don't change your service name. + +## Bring your own ingress + +You can also use your own ingress manifests. This is useful when you have more complex configurations, or you need specific URLs. + +Keep in mind that all the hosts you use in your ingress must end with`-$NAMESPACE.cloud.okteto.net`. + +### Let Okteto generate the host + +Okteto Cloud can automatically inject the right host names during the creation of your ingresses, while leaving the rest of the configuration intact. In order to take advantage of this feature, add the annotation below to your ingress' manifest. + +``` + dev.okteto.com/generate-host: "true" +``` + +Full example: + +```yaml +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + annotations: + dev.okteto.com/generate-host: "true" + name: hello-world +spec: + rules: + - http: + paths: + - backend: + serviceName: hello-world + servicePort: 8080 + path: / +``` + +We recommend you follow this option. This way your ingress configuration can be deployed on any Okteto Cloud namespace. \ No newline at end of file diff --git a/versioned_docs/version-1.5/cloud/volume-snapshots.mdx b/versioned_docs/version-1.5/cloud/volume-snapshots.mdx new file mode 100644 index 000000000..e13597c41 --- /dev/null +++ b/versioned_docs/version-1.5/cloud/volume-snapshots.mdx @@ -0,0 +1,175 @@ +--- +title: Volume Snapshots +description: Use volume snapshots in your development environments +sidebar_label: Volume Snapshots +id: use-volume-snapshots +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Volume snapshots allows you to initialize persistent volume claims with the contents of a preexisting volume snapshot. +Use volume snapshots when working with large datasets or if you want to create development environments with real data coming from your production or staging environments. + +## Requirements + + + + +Follow [this guide](self-hosted/administration/volume-snapshots.mdx) to enable Volume Snapshots in your cluster. + +Use a storage class provisioned by a CSI driver that [supports volume snapshots](https://kubernetes-csi.github.io/docs/snapshot-restore-feature.html) for the source persistent volume of your volume snapshots. + + + + +If your instance is hosted by Okteto, Volume Snapshots are enabled by default. + +**Important**: you need to use the `csi-okteto` storage classes for the source persistent volume of your volume snapshots. + + + + +## Using Volume Snapshots in your Development Environment + +Okteto enables developers to initialize persistent volume claims with the contents of a pre-existing volume snapshot. +The volume snapshot is created from a persistent volume claim and it can contain database backups, big files, images, a copy of your staging data, etc. + +In order to use volume snapshots with your development environment you need to: + +- [Create the source persistent volume](cloud/volume-snapshots.mdx#creating-the-persistent-volume) +- [Create a volume snapshot of the source persistent volume](cloud/volume-snapshots.mdx#creating-a-volume-snapshot) +- [Consume the volume snapshot in a new persistent volume](cloud/volume-snapshots.mdx#consuming-a-volume-snapshot) + +### Creating the Source Persistent Volume + +First, create the source persistent volume. This is the data that you want to be able to clone into your development environment. In the example below we use a database, but this could be anything that uses a volume for storage: databases, ML models, images, etc... +> If the default storage class of your cluster doesn't support volume snapshots, make sure you set the storage class to one that is compatible when creating your persistent volume. +Check the [requirements](cloud/volume-snapshots.mdx#requirements) section to learn more about the available storage classes in Okteto. + + + + + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + name: mysql-pvc +spec: + storageClassName: csi-okteto + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +``` + + + + +```yaml +services: + mysql: + image: mysql + volumes: + - mysql-pvc:/var/lib/mysql + +volumes: + mysql-pvc: + driver_opts: + class: csi-okteto +``` + + + + + +### Creating a Volume Snapshot + +After creating the source persistent volume, the next step is to create the Volume Snapshot. Volume snapshots are created with the content of the persistent volume at the time of creating the volume snapshot. Further updates on the persistent volume aren't reflected in the volume snapshot content. + +This step is independent of whether you created your persistent volume with Kubernetes manifests or a Docker Compose file: + +The following manifest creates a volume snapshot from the `mysql-pvc` persistent volume claim: + +```yaml +apiVersion: snapshot.storage.k8s.io/v1 +kind: VolumeSnapshot +metadata: + name: mysql-snapshot +spec: + volumeSnapshotClassName: okteto-snapshot-class + source: + persistentVolumeClaimName: mysql-pvc +``` + +### Consuming a Volume Snapshot +Finally, you can use the volume snapshot created in the previous step to populate a new persistent volume. +Use the `dev.okteto.com/from-snapshot-name` and `dev.okteto.com/from-snapshot-namespace` annotations on any persistent volume claim to tell Okteto to initialize your persistent volume claim from an existing volume snapshot, as shown below: + + + + +```yaml +apiVersion: v1 +kind: PersistentVolumeClaim +metadata: + annotations: + dev.okteto.com/from-snapshot-name: mysql-snapshot + dev.okteto.com/from-snapshot-namespace: staging + name: pvc-from-snapshot +spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 10Gi +``` + + + + +```yaml +services: + mongodb: + image: mysql + volumes: + - data:/var/lib/mysql + +volumes: + data: + labels: + dev.okteto.com/from-snapshot-name: mysql-snapshot + dev.okteto.com/from-snapshot-namespace: staging +``` + + + + +If the annotation `dev.okteto.com/from-snapshot-namespace` is not defined, Okteto will default to the namespace of the new persistent volume claim. + +Use the annotation `dev.okteto.com/skip-snapshot-if-same-namespace: "true"` to skip the data cloning operation if the source snapshot and the new persistent volume claim are in the same namespace. + +For a full end to end sample, check the following resources: + +- [How to Create a Development Environment with Realistic Data in Okteto Cloud](https://www.okteto.com/blog/how-to-create-and-use-data-clones-in-okteto-cloud/) blog post +- [How to Create and Use Data Clones in Okteto](https://www.okteto.com/blog/how-to-create-and-use-data-clones-in-okteto-video/) video tutorial diff --git a/versioned_docs/version-1.5/getting-started.mdx b/versioned_docs/version-1.5/getting-started.mdx new file mode 100644 index 000000000..daf96af66 --- /dev/null +++ b/versioned_docs/version-1.5/getting-started.mdx @@ -0,0 +1,87 @@ +--- +title: Install and Configure +description: In this guide, we'll go over the setup you need to get started with using Development Environments. +sidebar_label: Install and Configure +id: getting-started +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Okteto's Development Environments enable you to work directly with a deployed application and see your code changes live on the cloud as soon as you hit save. + +These Dev environments work using a combination of [Okteto Cloud](index.md), which is used to deploy your application, and [Okteto CLI](cloud/okteto-cli.mdx), which is used to launch the Dev Environment. This guide will teach how to get started with remote Development Environments. + +## Installing Okteto CLI + +Install the Okteto CLI following these steps: + +### MacOS / Linux + +```console +$ curl https://get.okteto.com -sSfL | sh +``` + +If you need a specific version you can set the OKTETO_VERSION environment variable: + +```console +$ curl https://get.okteto.com -sSfL | OKTETO_VERSION=2.3.3 sh +``` + +You can also install it via [brew](https://brew.sh/) by running: + +```console +$ brew install okteto +``` + +### Windows + +Download https://downloads.okteto.com/cli/okteto.exe and add it to your `$PATH`. + +You can also install it via [scoop](https://scoop.sh/) by running: + +```console +$ scoop install okteto +``` + +### GitHub + +Alternatively, you can directly download the binary [from GitHub](https://github.com/okteto/okteto/releases) or build it directly from the source code. + +## Configuring Okteto CLI with Okteto Cloud + +You can launch a remote Development Environment on [Okteto Cloud](https://cloud.okteto.com) or **any** Kubernetes cluster with the Okteto CLI. For this guide, we'll be using Okteto Cloud. + +The first thing you need to do is configure Okteto CLI to use Okteto Cloud. To do this, run the command below: + +```console +$ okteto context use https://cloud.okteto.com +``` + +You can confirm that your CLI is configured by running the command below: + +```console +$ okteto context list +``` +```console +Name Namespace Builder Registry +https://cloud.okteto.com * cindylopez tcp://buildkit.cloud.okteto.net:1234 registry.cloud.okteto.net +``` + +## Getting Your Application Ready + +For Okteto CLI to know how to launch your Development Environment, it needs an [Okteto manifest](cloud/okteto-cli.mdx#okteto-manifest). This manifest allows you to provide configuration for your Development Environments. +Okteto CLI will analyze any [existing manifests](cloud/okteto-cli.mdx#deployment-manifests) (Helm, Kubernetes, etc.) in your source code directory and help you write an Okteto manifest for your application. +The Okteto manifest is necessary in all cases except if you already have a Docker compose file configured for your application. + +If you don't have an Okteto manifest for your application, you can run `okteto init`. +This generates the Okteto manifest, which you can then edit based on your needs. +You can learn more about the manifest [here](reference/manifest.mdx). + +For the Getting Started guide, we already have the Okteto manifest configured for our application, so this step won't be needed. + +## Next Steps + +In this section, we installed Okteto CLI on our machine and configured it to work with Okteto Cloud. +[Next](using-dev-envs.mdx), we're going to launch our Dev Environment and fix a bug in a sample application. \ No newline at end of file diff --git a/versioned_docs/version-1.5/images/apitoken.png b/versioned_docs/version-1.5/images/apitoken.png new file mode 100644 index 000000000..85dbfe346 Binary files /dev/null and b/versioned_docs/version-1.5/images/apitoken.png differ diff --git a/versioned_docs/version-1.5/images/compose-endpoints.png b/versioned_docs/version-1.5/images/compose-endpoints.png new file mode 100644 index 000000000..931d5e585 Binary files /dev/null and b/versioned_docs/version-1.5/images/compose-endpoints.png differ diff --git a/versioned_docs/version-1.5/images/debug.png b/versioned_docs/version-1.5/images/debug.png new file mode 100644 index 000000000..9c1c921ba Binary files /dev/null and b/versioned_docs/version-1.5/images/debug.png differ diff --git a/versioned_docs/version-1.5/images/deploy.png b/versioned_docs/version-1.5/images/deploy.png new file mode 100644 index 000000000..9ef2f37fa Binary files /dev/null and b/versioned_docs/version-1.5/images/deploy.png differ diff --git a/versioned_docs/version-1.5/images/next-endpoints.png b/versioned_docs/version-1.5/images/next-endpoints.png new file mode 100644 index 000000000..eb4199bc5 Binary files /dev/null and b/versioned_docs/version-1.5/images/next-endpoints.png differ diff --git a/versioned_docs/version-1.5/images/next-ui-movies-fixed.png b/versioned_docs/version-1.5/images/next-ui-movies-fixed.png new file mode 100644 index 000000000..f42b017df Binary files /dev/null and b/versioned_docs/version-1.5/images/next-ui-movies-fixed.png differ diff --git a/versioned_docs/version-1.5/images/next-ui-movies.png b/versioned_docs/version-1.5/images/next-ui-movies.png new file mode 100644 index 000000000..0510d92fd Binary files /dev/null and b/versioned_docs/version-1.5/images/next-ui-movies.png differ diff --git a/versioned_docs/version-1.5/images/okteto-ui.png b/versioned_docs/version-1.5/images/okteto-ui.png new file mode 100644 index 000000000..b0fb4fa0b Binary files /dev/null and b/versioned_docs/version-1.5/images/okteto-ui.png differ diff --git a/versioned_docs/version-1.5/images/ui-cloud.png b/versioned_docs/version-1.5/images/ui-cloud.png new file mode 100644 index 000000000..4ceb36a07 Binary files /dev/null and b/versioned_docs/version-1.5/images/ui-cloud.png differ diff --git a/versioned_docs/version-1.5/images/ui-movies.png b/versioned_docs/version-1.5/images/ui-movies.png new file mode 100644 index 000000000..5c52e4dd4 Binary files /dev/null and b/versioned_docs/version-1.5/images/ui-movies.png differ diff --git a/versioned_docs/version-1.5/index.md b/versioned_docs/version-1.5/index.md new file mode 100644 index 000000000..4d56d1cda --- /dev/null +++ b/versioned_docs/version-1.5/index.md @@ -0,0 +1,28 @@ +--- +title: Welcome to Okteto! +description: This section will give you a brief overview of what all Okteto has to offer +sidebar_label: Overview +id: overview +--- + +Okteto is a platform to simplify the application development process by leveraging pre-configured cloud environments. This overview covers what Okteto offers and how you can get started. + +## Development Environments +Okteto's [Dev Environments](reference/development-environments.mdx) offer you a way to deploy and develop applications directly on the cloud. The traditional development workflow involves committing and pushing your changes and then waiting for the CI to build and deploy them before you can take a look. If you have to do this multiple times a day, not only is it frustrating, it is also extremely time-consuming, especially if multiple developers are using a single staging environment. + +Dev Environments solve this exact problem by allowing you to code locally on your machine but seeing your changes live deployed on a cluster **as soon as you hit save**! You don't have to spend time configuring a bunch of things for this - Okteto takes care of that for you. If you'd like to see this in action, head right to the [Quick Start Guide](getting-started.mdx). If you're looking for more in-detail documentation, you can find that [here](reference/development-environments.mdx). + +## Preview Environments +Using Okteto, you can configure [Preview Environments](cloud/preview-environments/overview.mdx) for your code repositories. Every pull request will then get deployed and will get its own separate sharable URL. This allows teams to browse the changes in a pull request even before it gets merged - without having to take care of any deployment-related setup. These URLs can also be shared with other stakeholders so that the review process isn't just limited to developers. + +You can learn how to configure Preview Environments by following the docs [here](cloud/preview-environments/overview.mdx). + +## Why Okteto? + +Okteto was built for developers, by developers. We understand how frustrating it is for developers to deal with the modern-day challenges of cloud-native development. + +Seeing what you're developing, deployed, while you're developing is a problem multiple tools try to solve - but not as effectively as Okteto. We know that developers only want to focus on writing code, and we provide just that by abstracting away the complexities of developing on a cloud environment. + +With Okteto, we hand back developers the freedom they love. Developers can focus on writing code and let Okteto take care of handling the boring parts of setting up and managing the development infrastructure! + +If you have more questions on how you can leverage Okteto to simplify your development process, we're here to [talk](https://okteto.com/schedule/)! 🙂 \ No newline at end of file diff --git a/versioned_docs/version-1.5/reference/cli.mdx b/versioned_docs/version-1.5/reference/cli.mdx new file mode 100644 index 000000000..a3084b183 --- /dev/null +++ b/versioned_docs/version-1.5/reference/cli.mdx @@ -0,0 +1,676 @@ +--- +title: Okteto CLI +description: The Okteto Command Line Interface is a unified tool to manage your development environments +id: cli +--- + +The Okteto Command Line Interface is a unified tool to manage your development environments. + +## Synopsis + +```console +$ okteto [options] [parameters] +``` + +Use `okteto command --help` for information on a specific command. The synopsis for each command shows its parameters and their usage. Optional parameters are shown in square brackets. + +| Options | Values | +| :----------- | :------------------------: | +| _--loglevel_ | _debug, info, warn, error_ | + +The amount of information outputted (defaults to _warn_). + +## Advanced configuration + +It is possible to handle timeouts from the client side when communicating with the buldkit daemon through the Okteto CLI. To do so, the following environment variables can be modified: + +- `OKTETO_KEEPALIVE_CLIENT_TIME_MS`: After this duration of time, if the client doesn't see any activity it will ping the server to see if the transport is still alive. If set below 10s, a minimum value of 10s will be used. The current default value is infinity. +- `OKTETO_KEEPALIVE_CLIENT_TIMEOUT_MS`: After sending a keepalive ping, the client waits for this duration of time and if no activity is seen even after that the connection is closed. The current default value is 20 seconds. +- `OKTETO_KEEPALIVE_CLIENT_PERMIT_WITHOUT_STREAM`: If true, the client sends keepalive pings even with no active RPCs. If false, when there are no active RPCs, Time and Timeout will be ignored and no keepalive pings will be sent. False by default. + + +## Available commands + +### analytics + +Enable / Disable analytics collection. Analytics are enabled by default + +```console +$ okteto analytics [parameters] +``` + +| Options | Description | +| :---------- | :--------------------------- | +| _--disable_ | Disables analytic collection | + +Okteto only collects information to help us understand how our users interact with the product. We don't collect any personally identifiable information. + +When you use the okteto CLI, the following information is collected: + +- The name of the action +- A timestamp of when it was run +- Your version of the CLI +- Your OS +- An anonymous machine ID (we use https://github.com/denisbrodbeck/machineid for this) +- A user ID if you are currently logged in to https://cloud.okteto.com +- An action ID (to correlate multiple actions performed during a command's execution) + +Please reach [out to us](mailto://hello@okteto.com) if you have any questions or concerns about the information collected. + +### build + +Build and push the images defined in the `build` section of your okteto manifest: + +```console +$ okteto build [service...] +``` + +If your [okteto context](reference/cli.mdx#context) points to an Okteto URL, images are built using the [Okteto Build Service](cloud/build.mdx). +Otherwise, images are built using your local Docker daemon. If you want to use another BuildKit instance, set the variable `BUILDKIT_HOST` to point to its address, using the format `HOST:PORT`. + +The following flags can be used (very similar to `docker build`): + +| Options | Type | Description | +| :--------------- | :------: | :------------------------------------------------------------------------- | +| _--file_ | (string) | The path to the okteto manifest | +| _--no-cache_ | (bool) | Do not use cache when building the image (default: `false`) | +| _--secret_ | (list) | Secret files exposed to the build. Format: `id=mysecret,src=/local/secret` | +| _--export-cache_ | (string) | Image tag for exported cache when build (optional) | +| _--cache-from_ | (list) | List of cache source images (optional) | + +> You can also use the `-f` to point to a Dockerfile. In this mode, `okteto build` will ignore your Okteto manifest, and directly build the image defined in the Dockerfile. Use this to build images that are not defined on your [Okteto manifest](https://www.okteto.com/docs/reference/manifest/). + +### context + +Set the default context. + +A context is a group of cluster access parameters. Each context contains a Kubernetes cluster, a user, and a namespace. +The current context is the default cluster/namespace for any Okteto CLI command. + +```console +$ okteto context +``` + +This will prompt you to select one of your existing contexts or to create a new one: + +```console +A context defines the default cluster/namespace for any Okteto CLI command. +Select the context you want to use: +Use the arrow keys to navigate: ↓ ↑ → ← + ▸ https://cloud.okteto.com (Okteto Cloud) * + minikube + staging + production + + Create new context +``` + +| Options | Type | Description | +| :--------------------------------------- | :------: | :-------------------------------------------------------------------------------------------------------------- | +| _--token_ | (string) | API token for authentication. Use this when scripting or if you don't want to use browser-based authentication. | +| --namespace | (string) | Namespace of your okteto context. | +| _--builder_ | (string) | URL of the builder service | + +When you run `okteto context`, an account will be created for your own `URL` if it's the first time you set the context in. +The CLI will exchange an authorization token with `URL` and save your API token and Okteto certificates information under `$HOME/.okteto/`. + +#### Using Environment Variables to authenticate + +Environment variables provide another way to specify your credentials. This is the recommended method when scripting tasks or when [creating preview environments](cloud/preview-environments/overview.mdx). + +The supported environment variables are: + +- `OKTETO_TOKEN`: Specifies the [personal access token](cloud/personal-access-tokens.mdx) to use +- `OKTETO_URL`: Specifies the Okteto URL. If missing, it defaults to https://cloud.okteto.com + +Available subcommands: + +#### delete + +Delete a context. + +For example, to delete the Okteto Cloud context, run: + +```console +$ okteto context delete https://cloud.okteto.com +``` + +#### list + +List available contexts. + +```console +$ okteto context list +``` + +```console +Name Namespace Builder Registry +https://cloud.okteto.com * cindy tcp://buildkit.cloud.okteto.net:1234 registry.cloud.okteto.net +minikube default docker - +``` + +#### show + +Print the current context. + +```console +$ okteto context show +``` + +```console +{ + "name": "https://cloud.okteto.com", + "token": "REDACTED", + "namespace": "cindy", + "builder": "tcp://buildkit.cloud.okteto.net:1234", + "registry": "registry.cloud.okteto.net", + "isOkteto": true +} +``` + +#### use + +Set the default context. + +```console +$ okteto context use +``` + +This will prompt you to select one of your existing contexts or to create a new one. + +You can also specify an Okteto URL: + +```console +$ okteto context use https://cloud.okteto.com +``` + +```console + ✓ Using context cindy @ cloud.okteto.com +``` + +Or a Kubernetes context: + +```console +$ okteto context use minikube +``` + +```console + ✓ Using context default @ minikube +``` + +### deploy + +Deploy your development environment by running the commands specified in the `deploy` section of your okteto manifest. +If the images in the `build` section don't exist, `okteto deploy` automatically builds and pushes all these images. +If the repositories in the `dependencies` section haven't been deployed yet, `okteto deploy` deploys these dependencies automatically. + +The command is executed relative to the path where the manifest is located. This means, that if the manifest is at any subfolder, the pipeline will use the context of the subfolder where the manifest is defined. + +```console +$ okteto deploy +``` + +##### Options + +| Options | Type | Description | +| :------------------------------------------ | :--------: | :------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _--build_ | (bool) | Force build of images in the `build` section (defaults to `false`) | +| --dependencies | (bool) | Force deployment of repositories in the `dependencies` section (defaults to `false`) | +| _--file_ | (string) | The location of the okteto manifest (defaults to `okteto.yml`) | +| _--name_ | (string) | The name of the development environment (defaults to the repo/folder name) | +| _--namespace_ | (string) | Overwrites the namespace where the development environment is deployed | +| _--timeout_ | (duration) | The duration to wait for the development environment deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s) | +| _--var_ | (list) | Set a pipeline variable (can be set more than once) | +| _--wait_ | (bool) | Wait until the pipeline finishes (defaults to false) | +| _--no-bash_ | (bool) | Execute the command using the container's default shell instead of bash (defaults to false) | + + +> Executed commands will be executed using bash unless the `--no-bash` flag has been specified. + +### destroy + +Destroy your development environment. +It automatically destroys all the Kubernetes resources created by [okteto deploy](reference/cli.mdx#deploy). +If you need to destroy external resources (like s3 buckets or other Cloud resources), use the [destroy](reference/manifest.mdx#destroy-string-optional) section of the Okteto Manifest. + +```console +$ okteto destroy +``` + +##### Options + +| Options | Type | Description | +| :--------------------------------------- | :------: | :------------------------------------------------------------------------------------------------------------------------------------------------------ | +| _--name_ | (string) | The name of the development environment (defaults to the folder name) | +| --namespace | (string) | overwrites the namespace where the development environment is deployed | +| _--timeout_ | (string) | The duration to wait for the development environment to be destroyed. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s) | +| _--volumes_ | (bool) | Destroy the persistent volumes created by the development environment (defaults to `false`) | +| _--wait_ | (bool) | Wait until the development environment is destroyed (defaults to `false`) | +| _--no-bash_ | (bool) | Execute the command using the container's default shell instead of bash (defaults to false) | +| _--all_ | (bool) | Destroy everything (defaults to `false`) | + +> Executed commands will be executed using bash unless the `--no-bash` flag has been specified. + + +> Resources annotated with `dev.okteto.com/policy: keep` will not be affected by the destroy action. + +### doctor + +Generates a doctor file with the okteto logs for a given development container: + +```console +$ okteto doctor [devName] +``` + +The `doctor` command should be run from the folder where you ran `okteto up`. + +The doctor file contains: + +- The `okteto.log` +- The syncthing logs of your development container +- A summary of your development container manifest +- A metadata file with information about your host machine's OS and architecture + +The doctor file is a handy way to collect all the okteto logs. Use it when filing an issue or asking [the Okteto community](http://community.okteto.com) for help. + +### down + +Deactivates your development container, stops the file synchronization service, and restores your previous deployment configuration for a given development container. + +```console +$ okteto down [devName] +``` + +The `down` command should be run from the same location as `okteto up`. + +| Options | Type | Description | +| :--------------------------------------- | :------: | :---------------------------------------------------------------------- | +| _--file_ | (string) | The path to the okteto manifest (default "okteto.yml") | +| --namespace | (string) | The namespace to use (defaults to the current okteto context namespace) | +| --context | (string) | The context to use (defaults to the current okteto context) | +| _--volumes_ | (bool) | Remove persistent volumes where your local folder is synched on remote | + +### endpoints + +List the public endpoints of your development environment. + +```console +$ okteto endpoints +``` + +| Options | Type | Description | +| :--------- | :------: | :------------------------------------ | +| _--output_ | (string) | Output format. One of: ['json', 'md'] | + +### exec + +Executes the `COMMAND` in your development container. +The command will fail if there's no active development container corresponding to the current folder. + +```console +$ okteto exec [devName] -- COMMAND +``` + +The `exec` command should be run from the same location as `okteto up`. + +| Options | Type | Description | +| :--------------------------------------- | :------: | :-------------------------------------------------------------- | +| _--file_ | (string) | The path to the okteto manifest (default "okteto.yml") | +| --namespace | (string) | The namespace to use (defaults to the current okteto namespace) | +| --context | (string) | The context to use (defaults to the current okteto context) | + +### help + +Displays the full help + +```console +$ okteto help +``` + +### init + +This command walks you through creating your Okteto Manifest. +It only covers the most common items, and tries to guess sensible defaults. +See the [Okteto Manifest documentation](reference/manifest.mdx) for more details about the Okteto Manifest. + +```console +$ okteto init +``` + +| Options | Type | Description | +| :--------------------------------------- | :-------: | :--------------------------------------------------------------------------------- | +| _--file_ | (string) | The path to the okteto manifest to create (default "okteto.yml") | +| _--replace_ | (string) | Replace an existing okteto manifest (default `false`) | +| --namespace | (string) | The namespace to use (defaults to the current okteto context namespace) | +| --context | (string) | The context to use (defaults to the current okteto context) | +| _-v1_ | (boolean) | Use the [okteto init v1](reference/cli.mdx#init) version (default `false`) | + +### kubeconfig + +Download credentials for the Kubernetes cluster selected via `okteto context`. + +```console +$ okteto kubeconfig +``` + +```console + i Updated kubernetes context 'cloud_okteto_com/cindy' in '/Users/cindy/.kube/config' +``` + +### namespace + +Configure the current namespace of the okteto context. + +```console +$ okteto namespace +``` + +This will prompt you to select one of your existing namespaces: + +```console +Select the namespace you want to use: +Use the arrow keys to navigate: ↓ ↑ → ← + ▸ cindy + + Create new namespace +``` + +```console + ✓ Using context cindy @ cloud.okteto.com +``` + +#### create + +Create a namespace. + +> This command is only available in clusters that have Okteto installed. + +```console +$ okteto namespace create test-cindy +``` + +```console + ✓ Namespace 'test-cindy' created + ✓ Using context test-cindy @ cloud.okteto.com +``` + +#### delete + +Delete a namespace. If the manifest includes `destroy` commands, they will be executed as part of this command. + +> This command is only available in clusters that have Okteto installed. + +```console +$ okteto namespace delete test-cindy +``` + +```console + ✓ Namespace 'test-cindy' deleted +``` + +#### list + +List existing namespace. + +> This command is only available in clusters that have Okteto installed. + +```console +$ okteto namespace list +``` + +```console +Namespace Status +demos-cindy Active +cindy * Active +``` + +#### use + +Set the default okteto namespace. + +```console +$ okteto namespace use cindy +``` + +```console + ✓ Using context cindy @ cloud.okteto.com +``` + +### pipeline + +Pipeline management commands + +```console +$ okteto pipeline [command] +``` + +Available subcommands: + +#### deploy + +Runs a job in the cluster that clones your repository and executes [okteto deploy](reference/cli.mdx#deploy) on it. +This is equivalent to clicking the **Launch Dev Environment** button on the Okteto UI and selecting a git repository. + +```console +$ okteto pipeline deploy +``` + +You need to be [logged in](reference/cli.mdx#context) to Okteto before running this command. + +##### Options + +| Options | Type | Description | +| :----------------- | :--------: | :---------------------------------------------------------------------------------------------------------------------------------------------------- | +| _--branch_ | (string) | The branch to deploy (defaults to the main branch) | +| _--file_ | (string) | The location of the okteto manifest. If not set, the [automatic deployment rules](cloud/okteto-cli.mdx#deployment-manifests) will be applied. | +| _--name_ | (string) | The name of the pipeline (defaults to the folder name) | +| _--namespace_ | (string) | The Kubernetes namespace to use (defaults to the current kube config namespace) | +| _--repository_ | (string) | The HTTPS url of the repository to deploy (e.g. https://github.com/okteto/movies) | +| _--skip-if-exists_ | (bool) | Skip the pipeline deployment if the pipeline already exists in the namespace (defaults to `false`) | +| _--timeout_ | (duration) | The duration to wait for the pipeline to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s) | +| _--var_ | (list) | Set a pipeline variable (can be set more than once) | +| _--wait_ | (bool) | Wait until the pipeline finishes (defaults to false) | + +#### destroy + +Runs a job in the cluster that clones your repository and executes [okteto destroy](reference/cli.mdx#destroy) on it. +This is equivalent to clicking the **Destroy** button on the Okteto UI. + +```console +$ okteto pipeline destroy +``` + +You need to be [logged in](reference/cli.mdx#context) to Okteto before running this command. + +##### Options + +| Options | Type | Description | +| :------------ | :------: | :--------------------------------------------------------------------------------------------------------------------------------------- | +| _--name_ | (string) | The name of the pipeline (defaults to the folder name) | +| _--namespace_ | (string) | The Kubernetes namespace to use (defaults to the current kube config namespace) | +| _--timeout_ | (string) | The duration to wait for the pipeline to be destroyed. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s) | +| _--volumes_ | (bool) | Destroy the persistent volumes created by the pipeline (defaults to false) | +| _--wait_ | (bool) | Wait until the pipeline is destroyed (defaults to false) | + +### preview + +[Preview environment](https://okteto.com/docs/cloud/preview-environments/preview-environments/) management commands. + +> This command is only available in clusters that have Okteto installed. + +```console +$ okteto preview [command] +``` + +#### deploy + +Deploy an okteto preview environment. + +```console +$ okteto preview deploy [name] +``` + +Run `okteto preview deploy` to automatically deploy a preview environment for your branch. + +You need to be [logged in](reference/cli.mdx#context) to Okteto before running this command. +Only users with [admin access](administration/dashboard.mdx) can deploy a global preview environment. + +| Options | Type | Description | +| :---------------------------------------- | :--------: | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| _--branch_ | (string) | The branch to deploy (defaults to your current branch) | +| _--file_ | (string) | The location of the okteto manifest. If not set, the [automatic deployment](cloud/deploy-from-git.mdx) rules will be applied. | +| --repository | (string) |  The url of the repository to deploy (e.g. https://github.com/okteto/movies) (defaults to your current git configuration repo) | +| _--scope_ | (string) | The scope of preview environment to create. Accepted values are ['personal', 'global']. A personal preview environment can only be accessed by its creator, while in a global preview environment all cluster users can access it. (defaults to personal) | +| _--sourceUrl_ |  (string) | The HTTPS url of the pull/merge request to deploy. | +| _--timeout_ | (duration) | The duration to wait for the preview deployment to complete. Any value should contain a corresponding time unit e.g. 1s, 2m, 3h (default 5m0s) | +| _--var_ | (list) | Set a preview environment variable (can be set more than once) | +| _--wait_ | (bool) | Wait until the preview deployment finishes (defaults to false) | + +#### destroy + +Destroy your okteto preview environment. + +```console +$ okteto preview destroy [name] +``` + +Run `okteto preview destroy` to destroy a given preview environment. + +You need to be [logged in](reference/cli.mdx#context) to Okteto before running this command. +Only users with administration privileges can destroy a global preview environment. +If the manifest includes `destroy` commands, they will be executed as part of this command. + +#### endpoints + +List the endpoints of a preview environment. + +```console +$ okteto preview endpoints [name] +``` + +You need to be [logged in](reference/cli.mdx#context) to Okteto before running this command. + +| Options | Type | Description | +| :--------- | :------: | :------------------------------ | +| _--output_ | (string) | Output format. One of: ['json'] | + +Output flag can be used to parse the endpoints and add them to your PR with a custom layout. + +#### list + +List all your okteto preview environments. + +```console +$ okteto preview list +``` + +Run `okteto preview list` to get the status and scope of your preview environments. + +You need to be [logged in](reference/cli.mdx#context) to Okteto before running this command. + +### logs + +Fetch the logs of your development environment. + +```console +$ okteto logs [serviceName] +``` + +The `okteto logs` command should be run from the same location than `okteto up`. + +The first argument is optional and it's a regex matching the name of the services you want to fetch the logs from. +For example, `okteto logs api` fetches the logs of any service starting with `api`. + + +| Options | Type | Description | +| :------------- | :--------: | :-------------------------------------------------------------------------------- | +| _--all | (boolean) | Fetch logs from the whole namespace | +| _--exclude_ | (string) | Exclude by service name (regular expression) | +| _--since_ | (duration) | Return logs newer than a relative duration like 5s, 2m, or 3h (default 48h0m0s) | +| _--tail_ | (int) | The number of lines from the end of the logs to show (default 100) | +| _--timestamps_ | (boolean) | Print timestamps | +| _--file_ | (string) | The path to the manifest file (default "okteto.yml") | +| _--namespace_ | (string) | The namespace to use to fetch the logs (defaults to the current okteto namespace) | +| _--context_ | (string) | The context to use to fetch the logs | + +### restart + +Restarts your development pods corresponding to the `services` section of the okteto manifest for a given development container. +This is useful to reload configurations that cannot be hot-reloaded. + +```console +$ okteto restart [devName] +``` + +The `restart` command should be run from the same location than `okteto up`. + +| Options | Type | Description | +| :------------ | :------: | :-------------------------------------------------------------- | +| _--file_ | (string) | The path to the manifest file (default "okteto.yml") | +| _--namespace_ | (string) | The namespace to use (defaults to the current okteto namespace) | +| _--context_ | (string) | The context to use (defaults to the current okteto context) | + +### status + +Status of the file synchronization process for a given development container: + +```console +$ okteto status [devName] --info +``` + +```console + i Local syncthing url: http://localhost:60539 + i Remote syncthing url: http://localhost:60538 + i Syncthing username: okteto + i Syncthing password: ac0ee34a-b1aa-4a41-bc67-cec3128b6cfd + ✓ Synchronization status: 100.00% +``` + +The `status` command should be run from the same location than `okteto up`. + +| Options | Type | Description | +| :------------ | :------: | :------------------------------------------------------------------- | +| _--file_ | (string) | The path to the manifest file (default "okteto.yml") | +| _--namespace_ | (string) | The namespace to use (defaults to the current okteto namespace) | +| _--context_ | (string) | The context to use (defaults to the current okteto context) | +| _--info_ | (bool) | Show syncthing links for troubleshooting the synchronization service | +| _--watch_ | (bool) | Watch for changes | + +### up + +Activate a development container. +If needed, `okteto up` builds the images and runs the deploy commands defined in your [Okteto Manifest](reference/manifest.mdx). + +```console +$ okteto up [devName] +``` + +When you run `okteto up`, okteto scales to zero the specified deployment and creates a mirror deployment. The mirror deployment is a copy of the original deployment manifest with the following development-time improvements: + +- Okteto overrides the container-level configuration of the original deployment with the values defined in your [okteto manifest](reference/manifest.mdx). A typical example of this is to replace the production container image with one that contains your development runtime. +- A bidirectional file [synchronization service](reference/file-synchronization.mdx) is started to keep your changes up to date between your local filesystem and your development container. +- Automatic local and remote port forwarding using [SSH](reference/ssh-server.mdx). This allows you to do things like access your cluster services via `localhost` or connect a remote debugger. +- A watcher service to keep the definition of the mirror deployment up to date with original deployment. + +It's worth noting that your development deployment inherits the original deployment manifest definition. +Therefore, the development deployment uses the same service account, environment variables, secrets, volumes, sidecars, ... than the original deployment, providing a fully integrated development environment. + +> Run [`okteto down`](#down) to restore your original deployment. + +| Options | Type | Description | +| :------------ | :------: | :--------------------------------------------------------------------------------------------------- | +| _--file_ | (string) | The path to the manifest file (default "okteto.yml") | +| _--namespace_ | (string) | The namespace to use (defaults to the current okteto namespace) | +| _--context_ | (string) | The context to use (defaults to the current okteto context) | +| _--env_ | (list) | Set environment variable in the dev container. | +| _--deploy_ | (bool) | Force execution of the commands in the `deploy` section of the okteto manifest (defaults to `false`) | +| _--reset_ | (bool) | Resets the file synchronization service. Use it if the file synchronization service stops working. | +| _--command_ | (list) | The command to execute in the dev container. This overrides the command specified in the `dev` section of the manifest | + +### version + +Displays the current installed version + +```console +$ okteto version +``` diff --git a/versioned_docs/version-1.5/reference/development-containers.mdx b/versioned_docs/version-1.5/reference/development-containers.mdx new file mode 100644 index 000000000..7c65b31e6 --- /dev/null +++ b/versioned_docs/version-1.5/reference/development-containers.mdx @@ -0,0 +1,83 @@ +--- +title: Development Environments +description: Configure development environments as code, side by side with your application +sidebar_label: Overview +id: development-environment +--- + +One of the advantages of using Okteto is the ability to configure development environments as code, side by side with your application. + +Instead of having to keep a wiki with a never-ending list of tools, dependencies, and scripts to install and run, you just have to clone your repository, deploy your application, and run `okteto up` to start developing in seconds. + +## Before you get started + +Setting up development environments using Okteto involves two main steps: + +1. Deploying your application code +2. Using `okteto up` to start your development container + +For using `okteto up`, you will need to install the Okteto CLI. Okteto CLI is an [open-source](https://github.com/okteto/okteto) tool that helps spin up development containers regardless of where you choose to deploy your application code as part of the first step. You can learn more about it by heading to the documentation [here](cloud/okteto-cli.mdx). + +Coming to the first step of deploying your application code, there are multiple options available for you to choose from. You can choose to deploy it on an existing cluster and use Okteto CLI to interact with this cluster. + +A second option available is Okteto Cloud. Using Okteto Cloud, you don't have to take care of setting up the infrastructure for deployment yourself. Okteto Cloud was built keeping dev environments in mind, so it also comes with useful [additional features](index.md) you would not find in a traditional cluster. To know more about it, you can head over to the Okteto Cloud [documentation](index.md). + +Another option available is Okteto Self-Hosted. Okteto Self-Hosted gives you all the features of Okteto Cloud - on your own infrastructure. This offers you full control of your Kubernetes infrastructure while delivering the same smooth experience you expect from Okteto Cloud. The Okteto Self-Hosted [documentation](self-hosted.mdx) covers how you can get started with it. + +## Getting started + +At a high level, a development environment is a Docker container that contains: + +- One or more language runtimes (e.g python, ruby, node) +- SDKs for your language runtime (e.g JDK, python-dev) +- Binary dependencies (e.g. openssl, git) +- Tools to manage and install dependencies (e.g. pip, bundler, yarn) +- Tools to run your tests and analyze your code (e.g nosetest, pylint) +- Your source code + +When you run the `okteto init` command on a local repository, `okteto` will analyze your source code and will guess the main programming language you're using. +Based on this, it will select a base development container configuration and create a default `okteto.yml` for you. + +For example, if your repository is mostly `golang`, it will look like this: + +```yaml +name: dev +image: golang:alpine +volumes: + - /go/pkg/ + - /root/.cache/go-build/ +forward: + - 8080:8080 +``` + +Out of the box, Okteto maintains pre-configured development images in this [GitHub repository](https://github.com/okteto/devenv) for the following languages: + +- dotnetcore +- golang +- java +- node +- php +- python +- ruby +- rust + +## Create your own + +The default development images are a great way to start. +They use the latest official docker image for your language runtime and include the most common developer tools and a custom bash prompt. +But they might not have everything you need. Your team might need to support a very specific version of your runtime, or you might need some extra tooling available. + +Do the following to create your own development image: + +1. Create a Dockerfile +1. Pick a base image +1. Add your extra dependencies, tools, and files +1. Build your image, tag it, and push it to your docker registry +1. Update the `image` key in your `okteto.yml` with your new image + +Besides following [Docker's best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/), we also recommend the following: + +- Create the docker image in CI, so it's clear how and when it was built +- Pin all your dependencies, so there aren't any surprises +- Keep the Dockerfile in your repository, next to your code +- When using [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), use your development image as the builder stage, so that you have the same tools and images in dev than in CI/CD diff --git a/versioned_docs/version-1.5/reference/development-environments.mdx b/versioned_docs/version-1.5/reference/development-environments.mdx new file mode 100644 index 000000000..53c2feb29 --- /dev/null +++ b/versioned_docs/version-1.5/reference/development-environments.mdx @@ -0,0 +1,84 @@ +--- +title: Development Environments +description: Configure development environments as code, side by side with your application +sidebar_label: Overview +id: development-environments +--- + +One of the advantages of using Okteto is the ability to configure development environments as code, side by side with your application. + +Instead of having to keep a wiki with a never-ending list of tools, dependencies, and scripts to install and run, you just have to clone your repository, deploy your application, and run `okteto up` to start developing in seconds. + +## Before you get started + +Setting up development environments using Okteto involves two main steps: + +1. Deploying your application code +2. Using `okteto up` to start your development container + +For using `okteto up`, you will need to install the Okteto CLI. Okteto CLI is an [open-source](https://github.com/okteto/okteto) tool that helps spin up development containers regardless of where you choose to deploy your application code as part of the first step. You can learn more about it by heading to the documentation [here](cloud/okteto-cli.mdx). + +Coming to the first step of deploying your application code, there are multiple options available for you to choose from. You can choose to deploy it on an existing cluster and use Okteto CLI to interact with this cluster. + +A second option available is Okteto Cloud. Using Okteto Cloud, you don't have to take care of setting up the infrastructure for deployment yourself. Okteto Cloud was built keeping dev environments in mind, so it also comes with useful [additional features](index.md) you would not find in a traditional cluster. To know more about it, you can head over to the Okteto Cloud [documentation](index.md). + +Another option available is Okteto Self-Hosted. Okteto Self-Hosted gives you all the features of Okteto Cloud - on your own infrastructure. This offers you full control of your Kubernetes infrastructure while delivering the same smooth experience you expect from Okteto Cloud. The Okteto Self-Hosted [documentation](self-hosted.mdx) covers how you can get started with it. + +## Getting started + +At a high level, a development container is a Docker container that contains: + +- One or more language runtimes (e.g python, ruby, node) +- SDKs for your language runtime (e.g JDK, python-dev) +- Binary dependencies (e.g. openssl, git) +- Tools to manage and install dependencies (e.g. pip, bundler, yarn) +- Tools to run your tests and analyze your code (e.g nosetest, pylint) +- Your source code + +When you run the `okteto init` command on a local repository, `okteto` will analyze your source code and will guess the main programming language you're using. +Based on this, it will select a base development container configuration and create a default `okteto.yml` for you. + +For example, if your repository is mostly `golang`, it will look like this: + +```yaml +dev: + my-app: + image: golang:alpine + volumes: + - /go/pkg/ + - /root/.cache/go-build/ + forward: + - 8080:8080 +``` + +Out of the box, Okteto maintains pre-configured development images in this [GitHub repository](https://github.com/okteto/devenv) for the following languages: + +- dotnetcore +- golang +- java +- node +- php +- python +- ruby +- rust + +## Create your own + +The default development images are a great way to start. +They use the latest official docker image for your language runtime and include the most common developer tools and a custom bash prompt. +But they might not have everything you need. Your team might need to support a very specific version of your runtime, or you might need some extra tooling available. + +Do the following to create your own development image: + +1. Create a Dockerfile +1. Pick a base image +1. Add your extra dependencies, tools, and files +1. Build your image, tag it, and push it to your docker registry +1. Update the `image` key in your `okteto.yml` with your new image + +Besides following [Docker's best practices](https://docs.docker.com/develop/develop-images/dockerfile_best-practices/), we also recommend the following: + +- Create the docker image in CI, so it's clear how and when it was built +- Pin all your dependencies, so there aren't any surprises +- Keep the Dockerfile in your repository, next to your code +- When using [multi-stage builds](https://docs.docker.com/develop/develop-images/multistage-build/), use your development image as the builder stage, so that you have the same tools and images in dev than in CI/CD diff --git a/versioned_docs/version-1.5/reference/docker-compose.mdx b/versioned_docs/version-1.5/reference/docker-compose.mdx new file mode 100644 index 000000000..b5bbad142 --- /dev/null +++ b/versioned_docs/version-1.5/reference/docker-compose.mdx @@ -0,0 +1,598 @@ +--- +title: Docker Compose Reference +description: Okteto allows you to develop applications using docker-compose files +sidebar_label: Docker Compose +id: compose +--- + +Docker Compose are for developers who don't want to deal with the complexities of Kubernetes manifests. +Okteto implements and extends the [Compose Specification](https://github.com/compose-spec/compose-spec) to make it easy to develop Docker Compose applications in Kubernetes. + +## Example + +```yaml +services: + vote: + build: vote + scale: 2 + environment: + - FLASK_ENV=development + command: python app.py + ports: + - 8080:8080 + volumes: + - ./vote:/src + + redis: + image: redis + ports: + - 6379 + volumes: + - redis:/data + +volumes: + redis: +``` + +The equivalent Kubernetes manifests would have more than 300 lines of yaml! + +## Schema reference + +### services ([object], optional) + +Define the services that make up your Docker Compose application. + +```yaml +services: + vote: + build: vote + scale: 2 + ports: + - 8080:8080 + + redis: + image: redis + ports: + - 6379 + volumes: + - redis:/data +``` + +Each service supports the fields in the [Compose Specification](https://github.com/compose-spec/compose-spec). +We summarize the most relevant ones below: + +#### build ([string|object], optional) + +Indicate how to build the image of this service when running `okteto build` or `okteto deploy --build`. +The value is the path to the build context: + +```yaml +build: vote +``` + +It can also be an object with these fields: + +- `context`: the build context. When the value supplied is a relative path, it is interpreted as relative to the location of the Docker Compose file (default: `.`) +- `dockerfile`: the path to the Dockerfile. It is a relative path to the build context (default: `Dockerfile`) +- `target`: build the specified stage as defined inside the Dockerfile. See the multi-stage build [Docker official docs](https://docs.docker.com/develop/develop-images/multistage-build/) for details. +- `args`: add build arguments, which are environment variables accessible only during the build process. Build arguments with a value containing a `$` sign are resolved to the environment variable value on the machine okteto is running on, which can be helpful for secret or machine-specific values. +- `export_cache`: image tag for exported cache when build. +- `cache_from`: list of images to import cache from. + +```yaml +build: + context: . + dockerfile: Dockerfile + target: prod + args: + - ENV1=prod + - ENV2=$VALUE +``` + +`okteto deploy --build` builds a new docker image, pushes it to the registry and redeploys your containers. +By default, it builds the images using the [Okteto Build Service](cloud/build.mdx). Set the variable `BUILDKIT_HOST` if you want to use your own BuildKit instance. + +#### cap_add ([string], optional) + +Add container capabilities. See `man 7 capabilities` for a full list. + +```yaml +cap_add: + - ALL +``` + +#### cap_drop ([string], optional) + +Drop container capabilities. See `man 7 capabilities` for a full list. + +```yaml +cap_drop: + - NET_ADMIN + - SYS_ADMIN +``` + +#### command (string, optional) + +Override the default command of the container image `CMD`. + +```yaml +command: --debug +``` + +`command` can also be a list of strings: + +```yaml +command: ["-p", "3000"] +``` + +#### depends_on ([string]|object, optional) + +Specify the conditions that the declared services must meet in order for the service to start. The condition must be one of the following: + +- `service_started`: Wait until the service is running. +- `service_healthy`: Wait for one of the ports of the dependent service to be available. +- `service_completed_successfully`: Wait until the dependent service has been successfully completed. + +```yaml +depends_on: + app: + condition: service_started + db: + condition: service_healthy + initialization-svc: + condition: service_completed_successfully +``` + +You can also express dependencies as a list of services. In this case it will be the same as setting the condition to `service_started`. + +```yaml +depends_on: + - app + - db + - initialization-svc +``` + +#### entrypoint (string, optional) + +Override the default entrypoint of the container image `ENTRYPOINT`. + +```yaml +entrypoint: yarn start +``` + +The entrypoint can also be a list of strings: + +```yaml +entrypoint: ["yarn", "start"] +``` + +#### env_file (string, optional) + +Add environment variables from a file to the containers of a service. +Environment variables declared in the [environment section](reference/docker-compose.mdx#environment-string-required) override these values. +This also holds true if those values are empty or undefined. + +```yaml +env_file: .env +``` + +`env_file` also accepts a list of files: + +```yaml +env_file: + - .env.frontend + - .env.api +``` + +#### environment ([string], optional) + +Add environment variables: + +```yaml +environment: + DEV_MODE: yes + DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres +``` + +#### healthcheck (object, optional) + +healthcheck declares a check that's run to determine whether or not containers for a +service are "healthy". + +- `start_period` (duration): Time between the start of the container and the initiation of the healthcheck. +- `interval` (duration): Time between a healthcheck and a subsequent new try. +- `timeout` (duration): Number of seconds after which the healthcheck times out. +- `retries` (int): Number of retries before healthcheck fails. +- `test` (string): Defines the command that will be run to check the container's health. It can be +either a string or a list. If it's a list, the first item must be either `NONE`, `CMD` or `CMD-SHELL`. +If it's a string, it's equivalent to specifying `CMD-SHELL` followed by that string. +- `http` (object): Defines the path and port that has to be tested on the container to set + the healthcheck as successful +- `x-okteto-readiness` (bool): Defines if the probe should be a readiness probe (default: `true`). +- `x-okteto-liveness` (bool): Defines if the probe should be a liveness probe (default: `false`). + +```yaml +healthcheck: + interval: 10s + timeout: 10m + retries: 5 + start_period: 30s + http: + path: / + port: 8080 +``` + +Healthchecks can also test a command as follows: + +```yaml +healthcheck: + interval: 10s + timeout: 10m + retries: 5 + start_period: 30s + test: echo 'db.runCommand({serverStatus:1}).ok' | mongo admin -u $MONGO_INITDB_ROOT_USERNAME -p $MONGO_INITDB_ROOT_PASSWORD --quiet | grep 1 +``` + +#### image (string, optional) + +The container image of each service. + +```yaml +image: okteto/vote:compose +``` + +If [`build`](reference/docker-compose.mdx#build-stringobject-optional) is defined, `image` is optional. Otherwise, it's required. + +#### labels ([string], optional) + +Specify labels for the service. They translates to Kubernetes annotations. + +```yaml +labels: + app: sample +``` + +#### ports ([int], optional) + +Ports exposed by each service. By default, they're only accessible from the cluster private network. + +```yaml +ports: + - 8080 +``` + +To make the port public, use the following notation: + +```yaml +ports: + - 8080:8080 +``` + +If you need to configure HTTPS routes, use [endpoints](reference/docker-compose.mdx#endpoints-object-optional) instead of configuring an NGINX container in your Docker Compose file. + +The following ports are never made public: + +| Protocol | Port | +| --------------- | ----------------------- | +| MySQL | 3306 | +| OracleDB | 1521,1830 | +| PostgreSQL | 5432 | +| SQL Server | 1433,1434 | +| MaxDB | 7210 | +| Neo4j | 7473 | +| ArangoDB | 8529 | +| Cassandra | 7000,7001,9042 | +| InfluxDB | 8086 | +| Elasticsearch | 9200,9300 | +| CouchDB | 5984 | +| MongoDB | 27017,27018,27019,28017 | +| Redis | 6379 | +| Riak | 8087,8088 | +| RethinkDB | 828015,29015,28015 | +| Solr | 7574,8983 | +| Golang debugger | 2345 | +| Node debugger | 5858,9229 | +| Java debugger | 5005 | +| Ruby debugger | 1234 | +| Python debugger | 4444,5678 | + +If you need make these ports public, you can use [endpoints](reference/docker-compose.mdx#endpoints-object-optional). + +#### scale (int, optional) + +Specify the number of containers running for each service (default: `1`). + +```yaml +scale: 2 +``` + +#### resources (object, optional) + +Configure resource [requests and limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits). + +```yaml +resources: + requests: + cpu: 300m + memory: 500Mi + limits: + cpu: 500m + memory: 800Mi +``` + +#### restart (string, optional) + +Defines the policy that the platform will apply on container termination. + +- `always/unless-stopped/any`: The default restart policy. The policy always restarts the container until its removal. +- `none/never/no`: The policy does not restart a container under any circumstances. +- `on-failure`: The policy restarts a container if the exit code indicates an error. + +```yaml +deploy: + restart_policy: + condition: on-failure + max_attempts: 3 +``` + +If the restart policy is other than always, the service will be translated to a Kubernetes Job. + +#### stop_grace_period (duration|int, optional) + +Specify how long to wait when attempting to stop a container before sending SIGKILL. +If no unit of time is given, the system will interpret the number in seconds. + +```yaml +stop_grace_period: 10s +``` + +#### volumes ([string], optional) + +Define volumes accessible by the containers of a service at a given path. + +```yaml +volumes: + - redis:/data +``` + +The volume `redis` must be defined in the [volumes section](reference/docker-compose.mdx#volumes-object-optional). + +The following notation is also accepted: + +```yaml +volumes: + - /data +``` + +Finally, host volumes are also supported: + +```yaml +volumes: + - .:/usr/app/src +``` + +Host volumes are added to your containers at deployment time. +In addition, `okteto up` uses host volumes to infer the [sync paths](reference/manifest.mdx#sync-string-required) between your local filesystem and your remote development container. + +#### working_dir (string, optional) + +Override the default working directory of the container image `WORKDIR`. + +```yaml +working_dir: "/app/code" +``` + +### volumes ([object], optional) + +List of volumes created by the Docker Compose file. +Volumes are mounted on the containers of a given service by referring the volume from the [volumes field](reference/docker-compose.mdx#volumes-string-optional) of the service. + +```yaml +volumes: + redis: + driver_opts: + size: 1Gi +``` + +Each volume has the following properties: + +#### labels (string, optional) + +Specify labels for the volume. They translates to Kubernetes annotations. + +```yaml +labels: + app: redis +``` + +#### driver_opts.class (string, optional) + +Specify the storage class of the volume. + +```yaml +driver_opts: + class: standard +``` + +#### driver_opts.size (string, optional) + +Specify the size of the volume. Defaults to 1Gi. + +```yaml +driver_opts: + size: 1Gi +``` + +## Environment variables + +There are multiple parts of Docker Compose files that deal with environment variables in one sense or another. +This section should help you find the information you need. + +### Environment variable substitution + +It’s possible to use environment variables in your shell to populate values inside your Docker Compose file: + +```yaml +services: + web: + image: "app:${TAG}" +``` + +If you have multiple environment variables, you can substitute them by adding them to a file named `.env`. + +### The .env file + +You can set default values for any environment variables referenced in your Docker Compose file in an environment file named `.env`. +The `.env` file is placed at the same folder than the Docker Compose file. + +For example: + +```console +$ cat .env +TAG=v1.5 +``` + +```console +$ cat docker-compose.yml +services: + web: + image: "app:${TAG}" +``` + +When you run `okteto deploy` the `web` container uses the image `app:v1.5`. + +> Values in the shell take precedence over those specified in the `.env` file. + +### extensions (object, optional) + +Specifies a configuration that can be used in other services using anchors. +Every top-level field starting with the prefix 'x-' will be interpreted as an extension. + +```yaml +x-function: &environment + environment: + DEV_MODE: yes + DB_HOST: postgres://${DB_HOST:-db}:${DB_PASSWORD}@postgres:5432/postgres +services: + app: + <<: *environment + image: okteto.dev/example +``` + +### Okteto Secrets + +You can also use your [Okteto Secrets](cloud/secrets.mdx) in your Docker Compose file. + +For example, if your have an Okteto Secret named `PASSWORD` whose value is `change-me!`, the following Docker Compose file: + +```yaml +services: + mysql: + image: mysql + environment: + - MYSQL_ROOT_PASSWORD=${PASSWORD} +``` + +will use `change-me!` for the value of the `MYSQL_ROOT_PASSWORD` environment variable of the `mysql` service when you run `okteto deploy`. + +> Values in the shell and/or the `.env` file take precedence over those specified in Okteto Secrets. + +## Okteto Cloud makes Docker Compose even more powerful! + +Okteto extends the Compose Specification to make it even easier for you and your team to build cloud-native applications. + +### endpoints ([object], optional) + +Endpoints expose HTTPS routes from outside the cluster to services within the cluster. +Use this instead of having to run a NGINX proxy in your Docker Compose file. + +```yaml +endpoints: + - path: / + service: frontend + port: 80 + - path: /api + service: api + port: 8080 +``` + +The endpoint uses the name of the development environment to generate a URL with the following format: https://NAME-NAMESPACE.cloud.okteto.net. + +Each endpoint has the following properties: + +#### path (string, required) + +The request path that will handle this route. + +#### service (string, required) + +The service that will receive the request. + +#### port (int, required) + +The port that will receive the request. + +If more than one endpoint is needed, you can declare multiple endpoints by using a map with the name of the endpoint and its specification: + +```yaml +endpoints: + landing: + - path: / + service: nginx + port: 80 + web: + - path: / + service: frontend + port: 80 + - path: /api + service: api + port: 8080 +``` + +In this case, the URLs `landing-NAMESPACE.cloud.okteto.net` and `web-NAMESPACE.cloud.okteto.net` are created. + +`endpoints` also accepts an extended notation to specify labels for each endpoint: + +```yaml +endpoints: + labels: + kubernetes.io/ingress.class: nginx + rules: + - path: / + service: frontend + port: 3000 + - path: /api + service: backend + port: 8080 +``` + +### update (annotation, optional) + +You can set the update policy of a service by setting the annotation `dev.okteto.com/update`. + +Depending on the kind of resource the acceptance values are different: +- rolling: Will deploy a service with zero downtime. Only allowed for deployments and stateful sets. +- recreate: Will wait until the current pod is deleted to start creating the new one. Only allowed on deployments. +- on-delete: Will wait until the current pod is deleted to start creating the new one. Only allowed on stateful sets. + +```yaml +services: + deployment: + image: python:alpine + labels: + "dev.okteto.com/update": rolling + entrypoint: python -m http.server 8080 + ports: + - 8080:8080 + sfs: + image: python:alpine + labels: + "dev.okteto.com/update": on-delete + entrypoint: python -m http.server 8080 + ports: + - 8080:8080 + volumes: + - /usr/src +``` + +> Remember that if you are on a docker-compose file the labels are translated into kubernetes annotations. \ No newline at end of file diff --git a/versioned_docs/version-1.5/reference/faqs.mdx b/versioned_docs/version-1.5/reference/faqs.mdx new file mode 100644 index 000000000..74cb64d2b --- /dev/null +++ b/versioned_docs/version-1.5/reference/faqs.mdx @@ -0,0 +1,248 @@ +--- +title: Frequently Asked Questions (FAQs) +description: Frequently asked questions about Okteto +sidebar_label: FAQs +id: faqs +--- + +## Can I use Okteto CLI with Minikube? + +Yes. Okteto CLI accelerates your development workflow regardless of where your Kubernetes cluster is running. + +If you can run `kubectl apply`, you can benefit from Okteto CLI. + +For Minikube, k3s, or similar local Kubernetes distributions, you can directly use our [open source project](https://github.com/okteto/okteto). For shared remote clusters, we recommend you take a look at [Okteto](https://okteto.com/) to handle credential management, namespace isolation, integration with GitHub among other things. + +## Why is Okteto better than traditional development? + +Among the many advantages, Okteto allows developers to: + +- Reduce local setup and eliminate integration issues by developing the same way your application runs in production +- Test your application as fast as you type code, without needing to use `docker` or `kubectl` in your inner loop cycle +- No more CPU cycles wasted in your machine. Hardware and network just limited by the power of the cloud +- Your development endpoints are always available. No need to expose your local machine to the internet through remote tunnels + +## How is Okteto different from other tools like Skaffold? + +Skaffold automates the workflow for building, pushing, and deploying your application. You iterate on your application source code locally and then deploy to local or remote Kubernetes clusters. + +Okteto's philosophy is to move development entirely to Kubernetes. The Skaffold pipeline, even though automated, is still slow. With Okteto, you code locally in your favorite IDE and Okteto automatically synchronizes your changes to your remote development environment. No commit, build, push, or deploy required. + +The main differences from tools like Skaffold are: + +- Okteto decouples deployment from development. You can deploy your application with `kubectl`, `Helm`, a serverless framework or even a CI job and use Okteto later to develop any component of your application +- Use any docker image as your remote development environment, with your favorite tools. Okteto doesn't require you to change the way you build, debug, or deploy your applications. Since builds are executed in your remote development environment, you benefit from fast incremental builds, hot reloaders, or the dependency caching offered by your programming language. Native builds are always faster than building images and redeploying containers +- You can integrate Okteto with your local IDE remote plugins, making it possible to execute your favorite IDE extensions and debuggers as you develop your application directly in Kubernetes +- Okteto provides bidirectional synchronization. For example, you can execute package managers like `npm` or `pip` in your remote development environment and the changes are synchronized back to your local file system + +## Is Okteto compatible with Flux/ArgoCD? + +Okteto decouples deployment from development, making it possible to use it with tools like Flux or ArgoCD. + +We recommend you to stop the Flux/ArgoCD reconciliation loop while running `okteto up`. For example, add this field to your Okteto Manifest to stop the Flux reconciliation loop: + +```yaml +annotations: + fluxcd.io/ignore: "true" +``` + +## How to use private images? + +In order to use your private registry credentials you must configure a [pull secret](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/) and use it in your Kubernetes manifests. + +Alternatively, follow these steps if you want to configure your private registry credentials for your default service account: + +- First, create a `docker-registry` secret with your registry credentials: + +```console +$ kubectl create secret docker-registry regcred --docker-server= --docker-username= --docker-password= --docker-email= +``` + +> More information on how to create `docker-registry` secrets [is available here](https://kubernetes.io/docs/tasks/configure-pod-container/pull-image-private-registry/#registry-secret-existing-credentials). + +- Update your service account to automatically inject the registry secret when deploying resources in the namespace: + +```console +$ kubectl patch serviceaccount default -p '{"imagePullSecrets": [{"name": "regcred"}]}' +``` + +> If your resources use a different `serviceAccountName`, replace `default` with that value in the command above. + +With this configuration, all the deployments, stateful sets, jobs, and development containers launched in your namespace will automatically use your registry credentials when pulling private images. + +## What types of Kubernetes services are supported in Okteto Cloud? + +`NodePort` or `LoadBalancer` services are not supported in Okteto Cloud. Okteto Cloud automatically translates `NodePort` or `LoadBalancer` services into ingress rules. More information is [available here](cloud/ssl.mdx). Okteto Cloud also configures [network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) for each namespace. Only traffic between the pods running in your namespaces is allowed, as well as external traffic to the internet. + +## What resource quotas are present in Okteto Cloud Namespaces? + +The following [resource quotas](https://kubernetes.io/docs/concepts/policy/resource-quotas/) are associated to every namespace created in Okteto Cloud: + + +| Resource | Quota | +|---|---| +| Namespaces | 5 | +| Pods | 10 | +| CPUs | 1CPU/pod with a maximum of 4CPUs/user | +| Memory | 3Gi/pod with a maximum of 8Gi/user | +| Storage | 5Gi | +| Services | 10 | +| Secrets | 50 | +| Config Maps | 50 | +| Persistent Volume Claims | 5 | + +## Are there any restrictions on applications deployed on Okteto Cloud? + +Okteto Cloud configures [pod security policies](https://kubernetes.io/docs/concepts/policy/pod-security-policy/) to limit the privileges of your applications. The following options are not allowed: `privileged`, `hostNetwork`, `allowPrivilegeEscalation`, `hostPID`, `hostIPC`. Mounting volume host paths is also not allowed. + +Apart from that, Okteto Cloud also uses [RBAC rules](https://kubernetes.io/docs/reference/access-authn-authz/rbac/) to limit the access to the Kubernetes API. The supported endpoints are: + +```yaml +- apiGroups: + - "" + resources: + - pods + - pods/log + - pods/exec + - pods/attach + - pods/portforward + - configmaps + - secrets + - services + - endpoints + - serviceaccounts + - events + - persistentvolumeclaims + - replicationcontrollers + verbs: + - '*' +- apiGroups: + - "" + resources: + - events + - limitranges + - namespaces + - namespaces/status + - resourcequotas + - resourcequotas/status + verbs: + - get + - list +- apiGroups: + - metrics.k8s.io + resources: + - pods + verbs: + - get + - list +- apiGroups: + - autoscaling + resources: + - horizontalpodautoscalers + verbs: + - '*' +- apiGroups: + - apps + resources: + - daemonsets + - deployments + - replicasets + - statefulsets + verbs: + - '*' +- apiGroups: + - batch + resources: + - cronjobs + - jobs + verbs: + - '*' +- apiGroups: + - extensions + resources: + - deployments + - ingresses + - replicasets + verbs: + - '*' +- apiGroups: + - networking.k8s.io + resources: + - ingresses + verbs: + - '*' +- apiGroups: + - rbac.authorization.k8s.io + resources: + - roles + - rolebindings + verbs: + - '*' +- apiGroups: + - policy + resources: + - poddisruptionbudgets + verbs: + - '*' +- apiGroups: + - apiextensions.k8s.io + resources: + - customresourcedefinitions + verbs: + - list + - watch +- apiGroups: + - helm.fluxcd.io + resources: + - helmreleases + - helmreleases/status + verbs: + - '*' +- apiGroups: + - helm.integrations.flux.weave.works + resources: + - fluxhelmreleases + verbs: + - '*' +- apiGroups: + - configuration.konghq.com + resources: + - kongplugins + - kongconsumers + - kongcredentials + - kongingresses + - tcpingresses + verbs: + - '*' +- apiGroups: + - openfaas.com + resources: + - functions + verbs: + - '*' +- apiGroups: + - litmuschaos.io + resources: + - chaosengines + - chaosexperiments + - chaosresults + verbs: + - '*' +- apiGroups: + - cert-manager.io + resources: + - certificates + verbs: + - list + - watch + - get +``` + +You can only create `Roles` restricted to the endpoints above. `RoleBindings` can only refer to `Roles` existing on your namespaces. + + +## Every time I make a change, tsc detects two changes: + +This is related to how syncthing interacts with `tsc`. Syncthing creates a temporary file and replaces the original file with the new one. + +To solve the problem you just add the flag `--synchronousWatchDirectory` to your `tsc` command. diff --git a/versioned_docs/version-1.5/reference/file-synchronization.mdx b/versioned_docs/version-1.5/reference/file-synchronization.mdx new file mode 100644 index 000000000..57cd0beee --- /dev/null +++ b/versioned_docs/version-1.5/reference/file-synchronization.mdx @@ -0,0 +1,51 @@ +--- +title: File Synchronization +description: Okteto keeps your local files synchronized with your development environment +sidebar_label: File Synchronization +id: file-synchronization +--- + +When you run `okteto up`, an instance of [Syncthing](https://syncthing.net/), a file synchronization service, will be automatically started to keep your local files synchronized with your development container. + +Syncthing provides a web UI to show the state of the file synchronization. You can get the syncthing endpoints and credentials of your development container by running `okteto status --info`: + +```console +$ okteto status --info +``` + +```console + i Local syncthing url: http://localhost:60539 + i Remote syncthing url: http://localhost:60538 + i Syncthing username: okteto + i Syncthing password: ac0ee34a-b1aa-4a41-bc67-cec3128b6cfd + ✓ Synchronization status: 100.00% +``` + +### Ignoring files + +If some files should not be synchronized between your local machine and your development environment, a file called `.stignore` can be created containing file patterns to ignore. +The `.stignore` file must be placed in the root of the folder. + +> The `okteto init` command will create a default `.stignore` tailored to the typical use cases of your programming language. + +The `.stignore` file contains a list of files or path patterns. +The _first pattern_ that matches will decide the fate of a given file. +The patterns follow the same syntax that `.gitignore` and `.dockerignore`. +More information on this [is available here](https://docs.syncthing.net/users/ignoring.html). + +``` +# default .stignore for a go-based project +okteto.yml +.git +*.exe +*.exe~ +*.dll +*.so +*.dylib + +# Test binary, built with go test -c +*.test + +# Output of the go coverage tool, specifically when used with LiteIDE +*.out +``` \ No newline at end of file diff --git a/versioned_docs/version-1.5/reference/known-issues.mdx b/versioned_docs/version-1.5/reference/known-issues.mdx new file mode 100644 index 000000000..402da5635 --- /dev/null +++ b/versioned_docs/version-1.5/reference/known-issues.mdx @@ -0,0 +1,32 @@ +--- +title: Known Issues +description: List of known issues +sidebar_label: Known Issues +id: known-issues +--- + +## Development environments do not hot-reload code changes + +If you are using a hot reloader in your development environment, it might happen that your hot reloader does not pick the code changes even when they are properly synchronized to your development environment. + +This is usually because the default *max watchers* value on your Kubernetes nodes is too low. To fix this issue, update the value of `/proc/sys/fs/inotify/max_user_watches` in all your Kubernetes nodes (we recommend the value `10048576`). + +For example, you can do it by running this command on each node: + +```console +$ sudo sysctl -w fs.inotify.max_user_watches=10048576 +``` + +[Okteto](https://okteto.com) uses a Daemon Set to apply this change automatically to every Kubernetes node. + +## The okteto prompt doesn't look right in Windows + +Okteto's remote prompt uses [ANSI escape sequences](https://devblogs.microsoft.com/commandline/whats-new-in-windows-console-in-windows-10-fall-creators-update/) to display the namespace and development environment name in different colors. + +If you're using PowerShell and the terminal looks funky, this feature might not enabled. Run the command below to enable ANSI Color globally: + +```console +Set-ItemProperty HKCU:\Console VirtualTerminalLevel -Type DWORD 1 +``` + +This [stackoverflow answer](https://stackoverflow.com/questions/51680709/colored-text-output-in-powershell-console-using-ansi-vt100-codes) has more information on this topic. diff --git a/versioned_docs/version-1.5/reference/manifest-migration.mdx b/versioned_docs/version-1.5/reference/manifest-migration.mdx new file mode 100644 index 000000000..eaac8bd08 --- /dev/null +++ b/versioned_docs/version-1.5/reference/manifest-migration.mdx @@ -0,0 +1,241 @@ +--- +title: Migrating to Okteto CLI 2.0 +description: Migrating to Okteto CLI 2.0 +sidebar_label: Migrating to Okteto CLI 2.0 +id: manifest-migration +--- + +The launch of [Okteto CLI 2.0](https://www.okteto.com/blog/announcing-the-launch-of-okteto-cli-2-0/) provides support for [Okteto Manifest v2](reference/manifest.mdx). + +The Okteto CLI 2.0 was introduced in [Okteto 0.11.0](self-hosted/install/releases.mdx#0110). Older versions of Okteto are not able to support version 2.0 of the CLI. + +The goal of the new manifest format is to have a single for defining the build, deployment, and development of your application. +The v2 manifest also consolidates the various actions possible with previous versions into one command, the improved `okteto up` command. +Previously, developers would have to run a series of commands, such as `okteto pipeline deploy` or `okteto stack deploy` and then `okteto up`. +The choice between using either the `pipeline` or `stack` commands was often a tripping point for our users and introduced needless complexity. +After a user figured this out, they were still not in setup to start active development. The user still needed to run the `okteto up` command. +With v2, a single run of `okteto up` will build images, deploy your application, and activate your development container. +Note that there are still commands for all the intermediary operations to use when desired: + +- `okteto build`: builds the images defined in the okteto manifest. +- `okteto deploy`: deploys your dev environment. +- `okteto deploy --build`: forces a build of the defined images before deploying the dev environment. +- `okteto up`: activates your dev container. +- `okteto up --deploy`: forces a redeploy of your development environment before activating your dev container. + +To facilitate the migration of a v1 okteto manifest to v2 we will cover the following scenarios: +- *Scenario 1* Developers with a docker-compose and a v1 manifest +- *Scenario 2* Developers with an okteto pipeline file and a v1 manifest +- *Scenario 3* Developers with a compose file, pipeline file and a v1 manifest + + +## Scenario 1: Compose and v1 Manifest + +This scenario provides an example of transitioning to a v2 manifest using a compose file and a v1 dev manifest. +You will continue to use your compose file, providing slight modifications by indexing the services and adding a deploy section. + +### v1 manifest + +#### okteto.yml + +```yaml +name: frontend +image: okteto/node:16 +command: bash +sync: + - .:/app +``` + +### v2 manifest + +#### okteto.yml + +```yaml +deploy: + compose: docker-compose.yml +dev: + frontend: + image: okteto/node:16 + command: bash + sync: + - .:/app +``` + +## Scenario 2: Pipeline and Multiple v1 Manifests + +The following scenario demonstrates converting from an okteto pipeline and v1 manifest to a single v2 manifest. +The example files are for a project that uses a pipeline to deploy a 3rd party PostgreSQL helm chart, build your app, and then deploy with a local helm chart. + +The conversion is peformed as follows: + +- Move the `deploy` section of the pipeline into a new `okteto.yml` v2 manifest. +- Take any `okteto build` commands from that `deploy` section and create a new and separate `build` section in the v2 manifest. +- Add all the v1 manifest instructions into indexed sections of the `dev` portion of the v2 manifest. + +The files used with okteto v1 are: + +- `okteto-pipeline.yml` -> The pipeline manifest. +- `frontend/okteto.yml` -> The v1 okteto manifest for the frontend service. +- `api/okteto.yml` -> The v1 okteto manifest for the api service. + +The migration to v2 would result in a single `okteto.yml` at the root of your project. +The example files are as follows: + +### v1 manifests + +#### okteto-pipeline.yml +```yaml +deploy: + - helm repo add bitnami https://charts.bitnami.com/bitnami + - helm upgrade --install postgresql bitnami/postgresql + - okteto build -t okteto.dev/frontend:${OKTETO_GIT_COMMIT} frontend + - okteto build -t okteto.dev/api:${OKTETO_GIT_COMMIT} api + - helm upgrade --install frontend frontend/chart --set image=okteto.dev/frontend:${OKTETO_GIT_COMMIT} + - helm upgrade --install api api/chart --set image=okteto.dev/api:${OKTETO_GIT_COMMIT} +``` + +#### frontend/okteto.yml +```yaml +name: frontend +image: okteto/node:16 +command: bash +sync: + - .:/app +``` + +#### api/okteto.yml +```yaml +name: api +image: okteto/golang:1 +command: bash +sync: + - .:/app +``` + +### v2 manifest + +The following variables are available within your v2 manifest to refer to the latest build of the images defined in the build section. + +- `${OKTETO_BUILD__IMAGE}`: the full image reference +- `${OKTETO_BUILD__REGISTRY}`: the registry URL where the image was pushed +- `${OKTETO_BUILD__REPOSITORY}`: the name of the image that was pushed +- `${OKTETO_BUILD__SHA}`: the latest tag and the SHA of the image + +For example, for the image `registry.cloud.okteto.net/cindy/hello-world:okteto`, you would have the following values: + +- `OKTETO_BUILD_HELLO_WORLD_IMAGE`: registry.cloud.okteto.net/cindy/hello-world@sha256:xxx +- `OKTETO_BUILD_HELLO_WORLD_REGISTRY`: registry.cloud.okteto.net +- `OKTETO_BUILD_HELLO_WORLD_REPOSITORY`: cindy/hello-world +- `OKTETO_BUILD_HELLO_WORLD_SHA`: okteto@sha256:xxx + +### okteto.yml +```yaml +build: + frontend: + context: frontend + api: + context: api + +deploy: + - helm repo add bitnami https://charts.bitnami.com/bitnami + - helm upgrade --install postgresql bitnami/postgresql + - helm upgrade --install frontend frontend/chart --set image=${OKTETO_BUILD_FRONTEND_IMAGE} + - helm upgrade --install api api/chart --set image=${OKTETO_BUILD_API_IMAGE} + +dev: + frontend: + image: okteto/node:16 + command: bash + sync: + - frontend:/app + api: + image: okteto/golang:1 + command: bash + sync: + - api:/app +``` + +## Scenario 3: Pipeline, Compose and Multiple v1 Manifests + +Scenario 3 is similar to Scenario 2, except we are no longer using a 3rd party helm chart to deploy PostgreSQL. +Now we are using a separate docker compose file called `db-compose.yml`. + +### v1 manifests + +We start with a similar v1 manifest and pipeline as in scenario 2 except the pipeline is using the deprecated `okteto stack` command to deploy `db-compose.yml` + +#### okteto-pipeline.yml +```yaml +deploy: + - okteto stack deploy -f db-compose.yml + - okteto build -t okteto.dev/frontend:${OKTETO_GIT_COMMIT} frontend + - okteto build -t okteto.dev/api:${OKTETO_GIT_COMMIT} api + - helm upgrade --install frontend frontend/chart --set image=okteto.dev/frontend:${OKTETO_GIT_COMMIT} + - helm upgrade --install api api/chart --set image=okteto.dev/api:${OKTETO_GIT_COMMIT} +``` + +#### frontend/okteto.yml +```yaml +name: frontend +image: okteto/node:16 +command: bash +sync: + - .:/app +``` + +#### api/okteto.yml +```yaml +name: api +image: okteto/golang:1 +command: bash +sync: + - .:/app +``` + +### v2 manifest + +The resulting v2 okteto manifest is again similar to that of scenario 2. +However, we have used extended notation in the `deploy` section to launch our PostgreSQL dependency from `db-compose.yml`. + +The following variables are available within your v2 manifest in order to refer to the latest build of the images defined in the build section. + +- `${OKTETO_BUILD__IMAGE}`: the full image reference +- `${OKTETO_BUILD__REGISTRY}`: the registry URL where the image was pushed +- `${OKTETO_BUILD__REPOSITORY}`: the name of the image that was pushed +- `${OKTETO_BUILD__SHA}`: the latest tag and the SHA of the image + +For example, for the image `registry.cloud.okteto.net/cindy/hello-world:okteto`, you would have the following values: + +- `OKTETO_BUILD_HELLO_WORLD_IMAGE`: registry.cloud.okteto.net/cindy/hello-world@sha256:xxx +- `OKTETO_BUILD_HELLO_WORLD_REGISTRY`: registry.cloud.okteto.net +- `OKTETO_BUILD_HELLO_WORLD_REPOSITORY`: cindy/hello-world +- `OKTETO_BUILD_HELLO_WORLD_SHA`: okteto@sha256:xxx + +### okteto.yml +```yaml +build: + frontend: + context: frontend + api: + context: api + +deploy: + compose: db-compose.yml + commands: + - helm upgrade --install frontend frontend/chart --set image=${OKTETO_BUILD_FRONTEND_IMAGE} + - helm upgrade --install api api/chart --set image=${OKTETO_BUILD_API_IMAGE} + +dev: + frontend: + image: okteto/node:16 + command: bash + sync: + - frontend:/app + api: + image: okteto/golang:1 + command: bash + sync: + - api:/app +``` + +Happy coding! diff --git a/versioned_docs/version-1.5/reference/manifest.mdx b/versioned_docs/version-1.5/reference/manifest.mdx new file mode 100644 index 000000000..b6c629162 --- /dev/null +++ b/versioned_docs/version-1.5/reference/manifest.mdx @@ -0,0 +1,882 @@ +--- +title: Okteto Manifest +description: Okteto's manifest for describing development environments +sidebar_label: Okteto Manifest +id: manifest +--- + +`okteto.yml` is a manifest format for describing development environments. + +The Okteto Manifest has three main sections: `build`, `deploy` and `dev`, to define how to build, deploy and develop your development environment. + +## Example + +```yaml +build: + api: + context: api + frontend: + context: frontend +deploy: + - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} +dev: + api: + command: ["bash"] + forward: + - 8080:8080 + - 9229:9229 + sync: + - api:/usr/src/app + frontend: + command: yarn start + sync: + - frontend:/usr/src/app +``` + +## Schema reference + +### build (object, optional) + +A list of images to build as part of your develoment environment. + +```yaml +build: + base: + context: . + api: + context: api + frontend: + context: frontend + dockerfile: Dockerfile + target: dev + depends_on: base + args: + SOURCE_IMAGE: ${OKTETO_BUILD_BASE_IMAGE} + secrets: + npmrc: .npmrc +``` + +Each image supports the following fields: + +- `image`: the name of the image to build and push. In clusters that have Okteto installed, this is optional (if not specified, the [Okteto Registry](cloud/registry.mdx) is used). +- `context`: the build context. Relative paths are relative to the location of the Okteto Manifest (default: `.`) +- `dockerfile`: the path to the Dockerfile. It's a relative path to the build context (default: `Dockerfile`) +- `target`: build the specified stage as defined inside the Dockerfile. See the [multi-stage official docs](https://docs.docker.com/develop/develop-images/multistage-build/) for details. +- `args`: add build arguments, which are environment variables accessible only during the build process. Build arguments with a value containing a `$` sign are resolved to the environment variable value on the machine okteto is running on. +- `secrets`: list of secrets exposed to the build. The value of each secret refers to a file. Okteto will resolve references containing a `$` sign in this fileto the environment variable value on the machine okteto is running on. +- `export_cache`: image tag for exported cache when build. +- `cache_from`: list of images to import cache from. +- `depends_on`: list of images that need to be built first. + +You can build all these images by running `okteto build`, or `okteto build xxx` to build a single one. + +In order to refer to these images from anywhere in your [Okteto Manifest](cloud/okteto-cli.mdx#okteto-manifest), you can use the following environment variables: + +- `${OKTETO_BUILD__IMAGE}`: the full image reference +- `${OKTETO_BUILD__REGISTRY}`: the registry URL where the image was pushed +- `${OKTETO_BUILD__REPOSITORY}`: the name of the image that was pushed +- `${OKTETO_BUILD__SHA}`: the latest tag and the SHA of the image + +For example, for the image `registry.cloud.okteto.net/cindy/hello-world:okteto`, you would have the following values: + +- `OKTETO_BUILD_HELLO_WORLD_IMAGE`: registry.cloud.okteto.net/cindy/hello-world@sha256:xxx +- `OKTETO_BUILD_HELLO_WORLD_REGISTRY`: registry.cloud.okteto.net +- `OKTETO_BUILD_HELLO_WORLD_REPOSITORY`: cindy/hello-world +- `OKTETO_BUILD_HELLO_WORLD_SHA`: okteto@sha256:xxx + +> if a `` name includes the symbol `-`, in the corresponding `OKTETO_BUILD_` environment variables, the symbol `-` will be replaced by `_`. For example, if `` is `name-with-hyphen`, the environment variable names will start with `$OKTETO_BUILD_NAME_WITH_HYPHEN_`. + +> Okteto will automatically add all the build environment variables from all previous images in the dependency chain as build arguments. To refer to them, remember to add the `ARG` instruction on your Dockerfile. + +### context (string, optional) + +The okteto context when the development environment is deployed. By default, it uses the current okteto context. + +For example, to force that your development environment is always created on your _minikube_ context, you can define: + +```yaml +context: minikube +``` + +You can use an environment variable to replace the context field, or any part of it: + +```yaml +context: $DEV_CONTEXT +``` + +### dependencies ([string], optional) + +A list of repositories you want to deploy as part of your development environment. + +> `dependencies` is only supported in clusters that have Okteto installed. + +```yaml +dependencies: + - https://github.com/okteto/movies-frontend +``` + +Use `okteto deploy --dependencies` to force the redeployment of your dependencies. + +There is also an extended notation to configure how to deploy your dependency: + +```yaml +dependencies: + frontend: + repository: https://github.com/okteto/movies-frontend + manifest: okteto.yml + branch: main + variables: + ENVIRONMENT: development + DEBUG: true + wait: true + timeout: 15m +``` + +Or: + +```yaml +dependencies: + frontend: + repository: https://github.com/okteto/movies-frontend + manifest: okteto.yml + branch: main + variables: + - ENVIRONMENT: development + - DEBUG: true + wait: true + timeout: 15m +``` + +When specifying the manifest path, the dependency deployment will use this path where the manifest is defined as the context. + +### deploy ([string], optional) + +A list of commands to deploy your development environment. + +It's usually a combination of `helm`, `kubectl`, and `okteto` commands. + +#### Deploy a Docker Compose file: + +If you are planning to develop with your `docker-compose` only, you should check out our [Getting Started](using-dev-envs.mdx) guide! + +You can also create an `okteto.yml` manifest to get even more out of okteto (e.g. to customize the folders that get synchronized, add extra environment variables, etc...). If you do that, you'll need to update the `deploy` section as follows: + +```yaml +deploy: + compose: docker-compose.yml +``` + +#### Deploy a helm chart: + +```yaml +deploy: + - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} +``` + +You can name your commands with the following syntax: + +```yaml +deploy: + - name: Deploy Movies App with Helm + command: helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} +``` + +#### Advanced deploy: + +There is an extended notation to deploy Docker compose files and [endpoints](reference/docker-compose.mdx#endpoints-object-optional) as part of your development environment: + +The `services` field allows us to deploy only a subset of the services in the Docker compose file. Only the `volumes` and `endpoints` of the services specified in the `services` field are deployed. + +```yaml +deploy: + compose: + - file: docker-compose.yml + services: + - frontend + - file: docker-compose.dev.yml + services: + - api + endpoints: + - path: / + service: frontend + port: 80 + - path: /api + service: api + port: 8080 +``` + +You can even merge deploy commands with docker-compose files: + +```yaml +deploy: + commands: + - helm upgrade --install movies chart --set api.image=${OKTETO_BUILD_API_IMAGE} --set frontend.image=${OKTETO_BUILD_FRONTEND_IMAGE} + compose: docker-compose.yml +``` + +You can share environment variables between steps by adding them to `$OKTETO_ENV`: + +```yaml +deploy: + - name: Set env value + command: echo "OKTETO_FOLDER=/app" >> $OKTETO_ENV + - name: Get env value + command: echo "$OKTETO_FOLDER" # Prints /app +``` + +### destroy ([string], optional) + +A list of commands to destroy external resources created by your development environment. + +`okteto destroy` automatically takes care of destroying all the Kubernetes resources created by `okteto deploy`. + +Use the `destroy` section if you create resources out of the scope of Kubernetes, like s3 buckets or RDS databases. + +```yaml +destroy: + - terraform destroy --auto-approve +``` + +### dev (object, optional) + +A list of development containers to define the behavior of [okteto up](reference/cli.mdx#up) and synchronize your code in your development environment. + +```yaml +dev: + api: + command: ["bash"] + forward: + - 8080:8080 + - 9229:9229 + sync: + - api:/usr/src/app + frontend: + command: yarn start + sync: + - frontend:/usr/src/app +``` + +The `name` of each development container must match the name of the Kubernetes Deployment or Statefulset that you want to put on development mode. +If the name of your Deployment or Statefulset is dynamicly generated, use the [selector](reference/manifest.mdx#selector-mapstringstring-optional) field to match the Deployment or Statefulset by labels. + +Each development container supports the following fields: + +#### affinity (Affinity, optional) + +Affinity allows you to constrain which nodes your development container is eligible to be scheduled on, based on labels on the node. + +```yaml +affinity: + podAffinity: + requiredDuringSchedulingIgnoredDuringExecution: + - labelSelector: + matchExpressions: + - key: role + operator: In + values: + - web-server + topologyKey: kubernetes.io/hostname +``` + +More information about affinity is [available here](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#affinity-and-anti-affinity). + +#### autocreate (bool, optional) + +If set to true, `okteto up` creates a deployment if `name` doesn't match any existing deployment in the current namespace (default: `false`). + +#### command (string, optional) + +Sets the command of your development container. If empty, it defaults to `sh`: + +```yaml +command: bundle exec thin -p 3000 +``` + +The command can also be a list: + +```yaml +command: ["bundle", "exec", "thin", "-p", "3000"] +``` + +#### container (string, optional) + +The name of the container in your deployment you want to put on development mode. By default, it takes the first one. + +#### environment ([string], optional) + +Add environment variables to your development container. If a variable already exists on your deployment, it will be overridden with the value specified on the manifest. + +Environment variables with only a key, or with a value with a `$` sign resolve to their values on the machine okteto is running on, which can be helpful for secret or machine-specific values. + +```yaml +environment: + environment: development + name: user-${USER:peter} ## will be replaced by the value of $USER or by "peter" if the the variable USER doe not exist + DBPASSWORD: ## will be given the value of $DBPASSWORD if it exists +``` + +##### envFiles + +Add environment variables to your development container from a file. + +```yaml +envFiles: + - .env1 + - .env2 +``` + +Environment variables declared in the environment section override these values. + +#### externalVolumes ([string], optional) + +A list of persistent volume claims (not managed by okteto) that you want to mount in your development container. +This is useful to share cache information between different development containers. +For example, to share the go cache between different development containers, you could define: + +```yaml +externalVolumes: + - go-cache:/root/.cache/go-build/ +``` + +on different okteto manifests. You can also mount a relative subpath of a given peristent volume claim: + +```yaml +externalVolumes: + - pvc-name:subpath:/var/lib/mysql +``` + +#### forward ([string], optional) + +A list of ports to forward from your development container. +The list should follow the `localPort:remotePort` notation and each element should be unique. + +You can also access other services running in your namespace by using the notation `localPort:remoteService:remotePort`. + +```yaml +forward: + - 8080:80 + - 5432:postgres:5432 +``` + +You can also use the extended notation below to configure the service to be exposed using a label selector or its name. + +```yaml +forward: + - localPort: 8080 + remotePort: 80 + name: app + - localPort: 5432 + remotePort: 5432 + labels: + app: db +``` + +Once your development container is up and running, you will be able to access the port directly by using `localhost:localPort`. + +> Common uses of port forwarding are: +> +> 1. Access a service via `localhost` instead of via an ingress +> 1. Remote debugging +> 1. Connect to a hot reloader via a websocket + +If Okteto can't forward a port (typically because they are already taken), the `okteto up` command will fail with an error. + +#### initContainer (object, optional) + +Allows you to override the okteto init container configuration of your development container. + +```yaml +initContainer: + image: okteto/bin:1.2.22 + resources: + requests: + cpu: 30m + memory: 30Mi + limits: + cpu: 30m + memory: 30Mi +``` + +#### interface (string, optional) + +Port forwards and reverse tunnels will be bound to this address. Defaults to `localhost`. + +```yaml +interface: 0.0.0.0 +``` + +#### image (string, optional) + +Sets the docker image of your development container. Defaults to the image specified in your deployment. + +> More information on development images [here](reference/development-environments.mdx) + +You can use an environment variable to replace the image, or any part of it: + +```yaml +image: okteto/dev:$USER +``` + +> More information on how to use private images for your development container [is available here](reference/faqs.mdx#how-to-use-private-images). + +#### imagePullPolicy (string, optional) + +The image pull policy of your development environment (default: `Always`) + +#### lifecycle (boolean, optional) + +If set to true, postStart and postStop lifecycle events are enabled when running `okteto up` (default: `false`). +More information about lifecycle events is [available here](https://kubernetes.io/docs/tasks/configure-pod-container/attach-handler-lifecycle-event/). + +Use the extended notation below to have more control over which events to enable/disable: + +```yaml +lifecycle: + postStart: false + postStop: true +``` + +- `postStart`: specifies if the postStart event is enabled when running `okteto up` (default: `false`). +- `postStop`: specifies if postStop event is enabled when running `okteto up` (default: `false`). + +#### metadata (object, optional) + +The metadata field allows to inject labels and annotations into your development container. + +```yaml +metadata: + annotations: + fluxcd.io/ignore: "true" + labels: + custom.label/dev: "true" +``` + +#### nodeSelector (map[string]string, optional) + +List of labels that the node must have to include the development container on it. + +```yaml +nodeSelector: + disktype: ssd +``` + +More information about nodeSelector is [available here](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector). + +#### persistentVolume (object, optional) + +Allows you to configure the okteto persistent volume: + +- `enabled`: enable/disable the use of persistent volumes (default: `true`) +- `storageClass`: the storage class of the volume (default: the `default` storage class) +- `size`: the size of the okteto persistent volume (default: `2Gi`) + +```yaml +persistentVolume: + enabled: true + storageClass: standard + size: 30Gi +``` + +Note the following limitations: + +- `persistentVolume.enabled` must be `true` if you use [services](reference/manifest.mdx#services-object-optional). +- `persistentVolume.enabled` must be `true` if you use [volumes](reference/manifest.mdx#volumes-string-optional). +- `persistentVolume.enabled` must be `true` if you want to share command history across development containers while developing an app. + +#### probes (boolean, optional) + +If set to true, liveness, readiness, and start probes are enabled when running `okteto up` (default: `false`). + +More information about probes is [available here](https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/). + +Use the extended notation below to have more control over which probes to enable/disable: + +```yaml +probes: + liveness: true + readiness: true + startup: true +``` + +- `liveness`: specifies if liveness probes are enabled when running `okteto up` (default: `false`). +- `readiness`: specifies if readiness probes are enabled when running `okteto up` (default: `false`). +- `startup`: specifies if startup probes are enabled when running `okteto up` (default: `false`). + +#### resources (object, optional) + +Allows you to override the resources configuration of your development container. +It follows the [same syntax used in Kubernetes](https://kubernetes.io/docs/concepts/configuration/manage-compute-resources-container). By default, `requests`, `limits` and `ephemeral-storage` are unset. + +```yaml +resources: + requests: + cpu: "250m" + memory: "64Mi" + ephemeral-storage: "64Mi" + limits: + cpu: "500m" + memory: "1Gi" + ephemeral-storage: "1Gi" +``` + +#### remote (integer, optional) + +The local port to use for SSH communication with your development environment. Defaults to a random value. + +```yaml +remote: 2222 +``` + +> Setting this value in the manifest is equivalent to starting your development container with the `okteto up --remote=2222` command. + +#### reverse ([string], optional) + +A list of ports to reverse forward from your development container to your local machine. +The list should follow the `remotePort:localPort` notation and each element should be unique. + +```yaml +reverse: + - 9000:9001 + - 8080:8080 +``` + +Once your development container is up and running, any requests to `0.0.0.0:remotePort` in the development container will be directed to `localhost:localPort` + +> Common uses of reverse forwarding are: +> +> 1. Remote debugging +> 1. Send events or logs to your local machine + +If Okteto can't reverse forward a port (typically because they're already taken), the `okteto up` command will fail with an error. + +#### secrets ([string], optional) + +A list of secrets that will be injected into your development container. +The format of a secret is `LOCAL_PATH:REMOTE_PATH:MODE`. `LOCAL_PATH` must exist, `REMOTE_PATH` must be an absolute path, and `MODE` is the remote file permissions in Base-8 (optional: defaults to `644`). + +```yaml +secrets: + - $HOME/.token:/root/.token:400 +``` + +#### securityContext (object, optional) + +Allows you to override the pod security context of your development container. + +Okteto supports overriding the `fsGroup`, `runAsUser`, `runAsGroup` and `capabilities` values. +They're not set by default, and they follow the [same syntax used in Kubernetes](https://kubernetes.io/docs/tasks/configure-pod-container/security-context/). + +```yaml +securityContext: + runAsUser: 1000 + runAsGroup: 2000 + fsGroup: 3000 + capabilities: + add: + - SYS_PTRACE +``` + +> Non-root Containers: +> +> If you're using a non-root container, and the runAsUser and runAsGroup values are not specified in your Kubernetes manifest, you need to set these values in your Okteto manifest. Remember to use the numeric ID in all cases, not the human readable name. + +#### selector (map[string]string, optional) + +The labels of the Kubernetes deployment/statefulset you want to put on development mode. +They must identify a single Kubernetes deployment/statefulset. + +```yaml +selector: + app.kubernetes.io/name: vote +``` + +#### serviceAccount (string, optional) + +Allows you to override the [serviceAccount](https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/) of your development container. + +```yaml +serviceAccount: default +``` + + +#### services ([object], optional) + +A list of services that you want to put on developer mode along your your development container. +The services work just like the development container, with one exception: they won't be able to start an interactive session. + +For example, imagine that you have a python-based application with an API and a Worker service. If you define the manifest as shown below, running `okteto up` would give you a remote terminal into the web development container, while synchronizing your changes with both web and worker. + +```yaml +dev: + web: + command: ["python", "manage.py", "runserver", "0.0.0.0:8080"] + sync: + - .:/app + services: + - name: worker + command: ["celery", "worker", "-A", "myproject.celeryconf", "-Q", "default", "-n", "default@%h"] + sync: + - .:/app +``` + +and both deployments, `web` and `worker` will mount your local folder `.` into the path `/app`. + +The supported keys for containers defined in this section are: + +1. `annotations` +1. `command` +1. `container` +1. `environment` +1. `image` +1. `labels` +1. `name` +1. `namespace` +1. `resources` +1. `sync` +1. `tolerations` +1. `workdir` + +They work the same as for the main container, except for the `command` and `name` keys. +For `services`, `command` defaults to the command specified in your deployment, instead of `sh`. +`labels` and `name` are mutually exclusive (for the main container, `name` is mandatory). + +#### sync ([string], required) + +Specifies local folders that must be synchronized to the development container. + +```yaml +sync: + - .:/code +``` + +`sync` supports relative paths and environment variable expansion: + +```yaml +sync: + - .:/code + - config:/etc/config + - $HOME/.ssh:/root/.ssh +``` + +> Use the `.stignore` file on each local folder to avoid synchronizing build artifacts, dependencies, or git metadata. [More information is available here](reference/file-synchronization.mdx) + +File sync can only update files that can be modified by your development container User ID. +If you are using okteto with persistent volumes, rememeber to set the field [securityContext.runAsUser](#securitycontext-object-optional) if your development container User ID is not `root`. + +> You can [use secrets](reference/manifest.mdx#secrets-string-optional) if you need to synchronize a single file instead of a folder + +There is also an extendend `sync` notation to fine tune the file synchronization service: + +```yaml +sync: + folders: + - .:/code + verbose: false + compression: true + rescanInterval: 100 +``` + +- `folders`: list of local folders that must be synchronized to the development container +- `verbose`: enable verbose logging for syncthing (default: `true`) +- `compression`: compress files before synchronizing them (default: `false`) +- `rescanInterval`: the synchronization service [rescan internal](https://docs.syncthing.net/users/syncing.html?highlight=rescan#scanning) in seconds. It can be set to zero to disable rescans (default: `300`) + +#### timeout (time, optional) + +Maximum time to be waiting for creating a development container until an error is returned. + +```yaml +timeout: 5m +``` + +You can also use the extended notation below to specify max time to be waiting for resources. + +```yaml +timeout: + default: 3m + resources: 5m +``` + +#### tolerations ([object], optional) + +A list of tolerations that will be injected into your development container. + +```yaml +tolerations: + - key: nvidia.com/gpu + operator: Exists +``` + +#### volumes ([string], optional) + +A list of paths in your development container that you want to associate to persistent volumes. +This is useful to persist information between `okteto up` executions, like downloaded libraries or cache information. +For example, to speed your go builds up, you could define: + +```yaml +volumes: + - /go/pkg/ + - /root/.cache/go-build/ +``` + +You can also mount a relative subpath of your local folder: + +```yaml +volumes: + - data:/var/lib/mysql +``` + +#### workdir (string, optional) + +Sets the working directory of your development container. + +### external (object, optional) + +A list of external resources that are part of your development environment. Use this section for resources that are deployed outside of the okteto cluster, like Cloud resources or dashboards. + +```yaml +external: + db: + notes: docs/database.md + icon: database + endpoints: + - name: db + url: https://localhost:3306 + functions: + notes: docs/lambdas.md + icon: function + endpoints: + - name: data-aggregator + url: https://fake-id.lambda-url.us-east-1.on.aws.aggregator + - name: data-processor + url: https://fake-id.lambda-url.us-east-1.on.aws.processor +``` + +#### endpoints ([object], required) + +Endpoints contain information on how to access the external resource. + +##### name (string, required) + +The name of the endpoint. + +##### url (string, optional) + +The url of the endpoint. + +##### Use dynamic endpoints for an external URL + +The url value related to an external resource can be set during deployment stage by sharing `$OKTETO_EXTERNAL_{EXTERNAL_NAME}_ENDPOINTS_{ENDPOINT_NAME}_URL`. This allows a value to be generated dynamically at deployment time. + +```yaml +deploy: + - name: Set endpoint URL dynamically + command: echo "OKTETO_EXTERNAL_DB_ENDPOINTS_DB_URL=$(aws deploy db --name foo)" >> $OKTETO_ENV + - name: Use dynamic value + command: echo ${OKTETO_EXTERNAL_DB_ENDPOINTS_DB_URL} +external: + db: + notes: docs/database.md + icon: database + endpoints: + - name: db + # url: is not set because it is dynamically generated in the deploy section. +``` + +If the url value is declared in both places, the one declared in the deploy section will prevail. + +#### icon (string, optional) + + Sets the icon that will be shown in the UI. The supported values for icons are listed below. If empty, it will default to `default`. + + - `container` + - `dashboard` + - `database` + - `default` + - `function` + - `graph` + - `storage` + +#### notes (string, optional) + +A relative path to a markdown file. The contents of the file will be displayed in the dashboard. You can use this to describe the resource or share instructions on how to use it. + +### forward ([string], optional) + +When declaring a global forward, Okteto will automatically handle port collision when two or more `okteto up` sessions are running simultaneously. If the `okteto up` session detects that the port is already in use, and said port is defined as global forward, `okteto up` will ignore the port collision and continue the `up` sequence. If the port is later available, `okteto up` session will automatically connect to it without interrupting the session. + +Global forward uses the same format than [forward](#forward-string-optional): + +```yaml +forward: + - 5432:postgres:5432 + - localPort: 8080 + remotePort: 80 + name: app +``` + +You can also indicate the service to expose using a label selector. + +```yaml +forward: + - localPort: 5432 + remotePort: 5432 + labels: + app: db +``` + +### icon (string, optional) + +The icon associated to your development environmen in the Okteto Dashboard (optional). + +### name (string, optional) + +The name of your development environment. It defaults to the name of your git repository. + +### namespace (string, optional) + +The namespace where the development environment is deployed. By default, it takes the current okteto context namespace. + +You can use an environment variable to replace the namespace field, or any part of it: + +```yaml +namespace: $DEV_NAMESPACE +``` + +## Environment variables + +There are multiple parts of the Okteto Manifest that deal with environment variables in one sense or another. +This section should help you find the information you need. + +### Substitute environment variables + +It’s possible to use environment variables in your shell to populate values inside an okteto manifest: + +```yaml +image: "node:${TAG}" +``` + +If you have multiple environment variables, you can substitute them by adding them to a file named `.env`. + +### The .env file + +You can set default values for any environment variables referenced in the okteto manifest in an environment file named `.env`. +The `.env` file is placed at the same folder than the okteto manifest. + +For example: + +```console +$ cat .env +TAG=v1.5 +``` + +```console +$ cat okteto.yml +... + image: "node:${TAG}" +... +``` + +When you any Okteto CLI command, `image` will be `node:v1.5`. + +> Values in the shell take precedence over those specified in the `.env` file. diff --git a/versioned_docs/version-1.5/reference/ssh-server.mdx b/versioned_docs/version-1.5/reference/ssh-server.mdx new file mode 100644 index 000000000..2d912b32b --- /dev/null +++ b/versioned_docs/version-1.5/reference/ssh-server.mdx @@ -0,0 +1,44 @@ +--- +title: SSH Server +description: Okteto runs an SSH server in your development container +sidebar_label: SSH Server +id: ssh-server +--- + +As part of enabling your development container, `okteto up` performs the following steps: + +- A [minimalist SSH server](https://github.com/okteto/remote) is injected into your development container +- A port forward is created from a local port to port 22 of the development container +- A host entry is added to your local `.ssh/config` file with the following values: + +``` +Host MANIFEST_NAME.okteto + HostName localhost + Port PORT + StrictHostKeyChecking no + UserKnownHostsFile /dev/null +``` + +> Use the [remote](reference/manifest.mdx#remote-integer-optional) field to configure the local port where the SSH server is exposed. + +The SSH server is used by `okteto up` to run remote commands and forward ports from/to your development containers. +The SSH server makes it possible to integrate your development container with IDEs that support remote development, such as [VS Code](https://marketplace.visualstudio.com/items?itemName=okteto.remote-kubernetes), [PHPStorm](https://confluence.jetbrains.com/pages/viewpage.action?pageId=57294700) or [PyCharm](https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html). + +### Connect using SSH + +Once the development container is up and running, you can SSH into it with the following command: + +```console +$ ssh -P PORT localhost +``` + +You can also SSH using the host entry added to your local SSH config: + +```console +$ ssh MANIFEST_NAME.okteto +``` + +### Secure by default + +When you run `okteto up` the first time, Okteto will create a SSH key pair for you and save it at `$HOME/.okteto/id_rsa_okteto` and `$HOME/.okteto/id_rsa_okteto.pub`. +The SSH server launched in your development container will be automatically configured to use these keys for authentication. diff --git a/versioned_docs/version-1.5/samples/aspnetcore.mdx b/versioned_docs/version-1.5/samples/aspnetcore.mdx new file mode 100644 index 000000000..456817463 --- /dev/null +++ b/versioned_docs/version-1.5/samples/aspnetcore.mdx @@ -0,0 +1,199 @@ +--- +title: Getting Started on Okteto Cloud with ASP.NET +description: This tutorial will show you how to create an account in Okteto Cloud and how to develop an ASP.NET sample application +sidebar_label: ASP.NET +id: aspnetcore +--- + +import Image from '@theme/Image'; + +[Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) gives instant access to secure Kubernetes namespaces to enable developers to code, build, and run Kubernetes applications entirely in the cloud. + +This tutorial will show you how to create an account in Okteto Cloud and how to develop an ASP.NET sample application. + +## Prerequisites + +- Install the latest version of the Okteto CLI. Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure Access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Deploy the ASP.NET Sample App + +Get a local version of the ASP.NET Sample App by executing the following commands: + +```console +$ git clone https://github.com/okteto/aspnetcore-getting-started +$ cd aspnetcore-getting-started +``` + +At the root of the directory, you'll find the `okteto.yaml` file. This describes how to [build](reference/manifest.mdx#build-object-optional) and [deploy](reference/manifest.mdx#deploy-string-optional) the ASP.NET Sample App. + +``` +build: + hello-world: + image: okteto.dev/aspnet-hello-world:1.0.0 + context: . + hello-world-dev: + context: . + target: dev +deploy: + - kubectl apply -f k8s.yml +``` + +Deploy your development environment by executing: + +```console +$ okteto deploy --build +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/aspnet-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +[+] Building 5.9s (11/11) FINISHED + ... + ✓ Image 'registry.cloud.okteto.net/cindy/aspnet-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'aspnet-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +Open your browser and go to the URL of the application. You can get the URL by logging into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) and clicking on the application's endpoint: + +Okteto Cloud UI ASP.NET + +Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto Cloud will [automatically create them](cloud/ssl.mdx) for you when you deploy your application. Cool no 😎? + +## Step 2: Activate your development container +The [dev](reference/manifest.mdx#dev-object-optional) section defines how to activate a development container for the ASP.NET Sample App: +``` +dev: + hello-world: + image: ${OKTETO_BUILD_HELLO_WORLD_DEV_IMAGE} + command: bash + environment: + - ASPNETCORE_ENVIRONMENT=Development + remote: 2222 +``` + +The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: +- `image`: the image used by the development container. More information on development images [here](reference/development-environments.mdx) and [dynamic value for the tag](reference/manifest.mdx#build-object-optional) +- `command`: the start command of the development container. +- `environment`: the environment variables added or overwritten in your development container. +- `remote`: the local port to use for SSH communication with your development environment. + +Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. +This is useful to avoid synchronizing binaries, build artifacts, or git metadata. + +Next, execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Namespace: cindy + Name: hello-world + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application by running the following command: + +```console +default:hello-world app> dotnet watch run +``` + +```console +dotnet watch ⌚ Polling file watcher is enabled +dotnet watch 🔥 Hot reload enabled. For a list of supported edits, see https://aka.ms/dotnet/hot-reload. + 💡 Press "Ctrl + R" to restart. +dotnet watch 🔧 Building... + Determining projects to restore... + All projects are up-to-date for restore. + helloworld -> /okteto/bin/Debug/netcoreapp6.0/helloworld.dll +dotnet watch 🚀 Started +warn: Microsoft.AspNetCore.Server.Kestrel[0] + Overriding address(es) 'https://localhost:5001, http://localhost:5000'. Binding to endpoints defined via IConfiguration and/or UseKestrel() instead. +info: Microsoft.Hosting.Lifetime[14] + Now listening on: http://0.0.0.0:5000 +dotnet watch 🌐 Unable to launch the browser. Navigate to http://0.0.0.0:5000 +info: Microsoft.Hosting.Lifetime[0] + Application started. Press Ctrl+C to shut down. +info: Microsoft.Hosting.Lifetime[0] + Hosting environment: Development +info: Microsoft.Hosting.Lifetime[0] + Content root path: /okteto +``` + +Go back to the browser and reload the page to test that your application is running. + +## Step 3: Develop directly in Okteto Cloud + +Open the file `Controllers/HelloWorldController.cs` in your favorite local IDE and modify the response message on line 25 to be *Hello world from Okteto!*. Save your changes. + +```csharp + [HttpGet] + public string Get() + { + return "Hello world from Okteto!"; + } +``` + +Take a look at the development container shell and notice how the changes are detected by `dotnet watch run` and automatically built and reloaded. + +```console +info: Microsoft.Hosting.Lifetime[0] + Application is shutting down... +watch : Exited +watch : File changed: /src/Controllers/HelloWorldController.cs +watch : Started +info: Microsoft.Hosting.Lifetime[0] + Now listening on: http://0.0.0.0:5000 +info: Microsoft.Hosting.Lifetime[0] + Application started. Press Ctrl+C to shut down. +info: Microsoft.Hosting.Lifetime[0] + Hosting environment: Development +info: Microsoft.Hosting.Lifetime[0] + Content root path: /src +``` + +Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! + +## Step 4: Debug directly in Okteto Cloud + +Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in VS Code using the VS dotnet debugger. + +For this step, we're going to use the `C#` extension for VS Code. If you don't have it, you can [install it here](https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp#review-details). You might need to restart your VS Code instance. + +Open `HelloWorldController.cs` in VS Code, set a breakpoint on line `26` and press `F5`. VS Code will connect to your development container via SSH and give you a list of processes you can attach to. Scroll through the list and select the `helloworld` process, as shown below (you can also type `helloworld` in the search bar directly). + +ASP.NET processes to attach to + +Once you select the process, VS Code will switch to debug view, launch the debugger, and attach it to the process you just selected. You'll know it's finished when the status bar at the bottom turns orange. + +ASP.NET connection status bar + +Go back to the browser and reload the page. As soon as the service receives the request, the execution will halt at your breakpoint and VS Code will jump to the front of the screen. You can then inspect the request, the available variables, etc. + +ASP.NET core debug + +Your code is executing in Okteto Cloud, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +> Okteto lets you develop your applications directly in Kubernetes. This way you can: +> - Eliminate integration issues by developing in a realistic environment +> - Test your application end to end as fast as you type code +> - No more CPU cycles wasted in your machine. Develop at the speed of the cloud! + +Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. \ No newline at end of file diff --git a/versioned_docs/version-1.5/samples/golang.mdx b/versioned_docs/version-1.5/samples/golang.mdx new file mode 100644 index 000000000..860f59050 --- /dev/null +++ b/versioned_docs/version-1.5/samples/golang.mdx @@ -0,0 +1,216 @@ +--- +title: Getting Started on Okteto Cloud with Go +description: This tutorial will show you how to develop a Go sample application +sidebar_label: Go +id: golang +--- + +import Image from '@theme/Image'; + +[Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) gives instant access to secure Kubernetes namespaces to enable developers to code, build, and run Kubernetes applications entirely in the cloud. + +This tutorial will show you how to develop and debug a Go sample application running in Okteto Cloud. + +## Prerequisites + +- Install the latest version of the Okteto CLI. Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Deploy the Go Sample App + +Get a local version of the Go Sample App by executing the following commands: + +```console +$ git clone https://github.com/okteto/go-getting-started +$ cd go-getting-started +``` + +At the root of the directory, you'll find the `okteto.yaml` file. This describes how to [build](reference/manifest.mdx#build-object-optional) and [deploy](reference/manifest.mdx#deploy-string-optional) the Go Sample App. + +```yaml +build: + hello-world: + image: okteto.dev/go-hello-world:1.0.0 + context: . + +deploy: + - kubectl apply -f k8s.yml +``` + +Deploy your development environment by executing: + +```console +$ okteto deploy --build +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/go-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +... + ✓ Image 'registry.cloud.okteto.net/cindy/go-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'go-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +Log into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) and click on the URL of the application: + +Okteto Cloud UI golang + +Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto Cloud will [automatically create them](cloud/ssl.mdx) for you when you deploy your application. Cool no 😎? + +## Step 2: Activate your development container + +The [dev](reference/manifest.mdx#dev-object-optional) section defines how to activate a development container for the Go Sample App: + +```yaml +dev: + hello-world: + image: okteto/golang:1 + command: bash + sync: + - .:/usr/src/app + volumes: + - /go + - /root/.cache + securityContext: + capabilities: + add: + - SYS_PTRACE + forward: + - 2345:2345 +``` + +The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: + +- `image`: the image used by the development container. More information on development images [here](reference/development-environments.mdx). +- `command`: the start command of the development container. +- `sync`: the folders that will be synchronized between your local machine and the development container. +- `volumes`: a list of paths in your development container to be mounted as persistent volumes. For example, this can be used to persist the Go cache. +- `securityContext`: `SYS_PTRACE` is a capability required by the Go debugger. +- `forward`: a list of ports to forward from your development container to locahost in your machine. This is needed to configure the Go debugger. + +Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. +This is useful to avoid synchronizing binaries, build artifacts, git metadata, or dependencies like the `vendor` folder. + +Next, execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Development environment 'go-getting-started' already deployed. + ✓ Images successfully pulled + ✓ Files synchronized + Context: cloud.okteto.com + Namespace: cindy + Name: hello-world + Forward: 2345 -> 2345 + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application by running the following command: + +```console +cindy:hello-world app> go run main.go +``` + +```console +Starting hello-world server... +``` + +Go back to the browser, and reload the page to test that your application is running. + +## Step 4: Develop directly on Okteto Cloud + +Open the file `main.go` in your favorite local IDE and modify the response message on line 17 to be *Hello world from Okteto!*. Save your changes. + +```golang +func helloServer(w http.ResponseWriter, r *http.Request) { + fmt.Fprint(w, "Hello world from Okteto!") +} +``` + +Okteto will synchronize your changes to your development container. +Cancel the execution of `go run main.go` from the development container shell by pressing `ctrl + c`. +Rerun your application: + +```console +cindy:hello-world app> go run main.go +``` + +```console +Starting hello-world server... +``` + +Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! + +## Step 5: Debug directly on Okteto Cloud + +Okteto enables you to debug your applications directly from your favorite IDE. +Let's take a look at how that works in VS Code, one of the most popular IDEs for Go development. +If you haven't done it yet, install the [Go extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go) available from Visual Studio marketplace. + +Cancel the execution of `go run main.go` from the development container shell by pressing `ctrl + c`. +Rerun your application in debug mode: + +```console +cindy:hello-world app> dlv debug --headless --listen=:2345 --log --api-version=2 +``` + +```console +API server listening at: [::]:2345 +2019-10-17T14:39:24Z info layer=debugger launching process with args: [/usr/src/app/__debug_bin] +``` + +In your local machine, open VS Code, and install the [Go extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode.Go). + +The sample application is already configured for remote debugging. +Open the _Debug_ view in VS Code and run the *Connect to okteto* debug configuration (or just press the F5 shortcut) to start the remote debugger: + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Connect to okteto", + "type": "go", + "request": "attach", + "mode": "remote", + "remotePath": "/usr/src/app", + "port": 2345, + "host": "127.0.0.1" + } + ] +} +``` + +> You should be replacing the value of `remotePath` with wherever your application code is. + +Add a breakpoint on `main.go`, line 17. Go back to the browser, and reload the page. +The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... + +debugging in Okteto with golang + +Your code is executing in Okteto Cloud, but you can debug it from your local machine without any extra services or tools. +Pretty cool no? 😉 + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +> Okteto lets you develop your applications directly on Kubernetes. This way you can: +> - Eliminate integration issues by developing in a realistic environment +> - Test your application end to end as fast as you type code +> - No more CPU cycles wasted in your machine. Develop at the speed of the cloud! + +Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. diff --git a/versioned_docs/version-1.5/samples/images/aspnetcore-attach.png b/versioned_docs/version-1.5/samples/images/aspnetcore-attach.png new file mode 100644 index 000000000..ce32ab3db Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/aspnetcore-attach.png differ diff --git a/versioned_docs/version-1.5/samples/images/aspnetcore-connected.png b/versioned_docs/version-1.5/samples/images/aspnetcore-connected.png new file mode 100644 index 000000000..3a483aec4 Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/aspnetcore-connected.png differ diff --git a/versioned_docs/version-1.5/samples/images/aspnetcore-debug.png b/versioned_docs/version-1.5/samples/images/aspnetcore-debug.png new file mode 100644 index 000000000..2b8cdf6c5 Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/aspnetcore-debug.png differ diff --git a/versioned_docs/version-1.5/samples/images/golang-debug.png b/versioned_docs/version-1.5/samples/images/golang-debug.png new file mode 100644 index 000000000..9c1c921ba Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/golang-debug.png differ diff --git a/versioned_docs/version-1.5/samples/images/java-debug.png b/versioned_docs/version-1.5/samples/images/java-debug.png new file mode 100644 index 000000000..815ac2749 Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/java-debug.png differ diff --git a/versioned_docs/version-1.5/samples/images/java-halt.png b/versioned_docs/version-1.5/samples/images/java-halt.png new file mode 100644 index 000000000..66e9d3929 Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/java-halt.png differ diff --git a/versioned_docs/version-1.5/samples/images/node-halt.png b/versioned_docs/version-1.5/samples/images/node-halt.png new file mode 100644 index 000000000..a1de027b0 Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/node-halt.png differ diff --git a/versioned_docs/version-1.5/samples/images/okteto-ui.png b/versioned_docs/version-1.5/samples/images/okteto-ui.png new file mode 100644 index 000000000..b0fb4fa0b Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/okteto-ui.png differ diff --git a/versioned_docs/version-1.5/samples/images/php-halt.png b/versioned_docs/version-1.5/samples/images/php-halt.png new file mode 100644 index 000000000..4e53b2eee Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/php-halt.png differ diff --git a/versioned_docs/version-1.5/samples/images/python-connected.png b/versioned_docs/version-1.5/samples/images/python-connected.png new file mode 100644 index 000000000..dad5d6f64 Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/python-connected.png differ diff --git a/versioned_docs/version-1.5/samples/images/python-debug.png b/versioned_docs/version-1.5/samples/images/python-debug.png new file mode 100644 index 000000000..0dbc685dd Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/python-debug.png differ diff --git a/versioned_docs/version-1.5/samples/images/ruby-halt.png b/versioned_docs/version-1.5/samples/images/ruby-halt.png new file mode 100644 index 000000000..6f5ef59d7 Binary files /dev/null and b/versioned_docs/version-1.5/samples/images/ruby-halt.png differ diff --git a/versioned_docs/version-1.5/samples/java.mdx b/versioned_docs/version-1.5/samples/java.mdx new file mode 100644 index 000000000..e6eef911f --- /dev/null +++ b/versioned_docs/version-1.5/samples/java.mdx @@ -0,0 +1,243 @@ +--- +title: Getting Started on Okteto Cloud with Java +description: This tutorial will show you how to develop a Java sample application +sidebar_label: Java +id: java +--- + +import Image from '@theme/Image'; + +[Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) gives instant access to secure Kubernetes namespaces to enable developers to code, build, and run Kubernetes applications entirely in the cloud. + +This tutorial will show you how to develop and debug a Java sample application running in Okteto Cloud. + +## Prerequisites + +- Install the latest version of the Okteto CLI. . Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Deploy the Java Sample App + +Get a local version of the Java Sample App by executing the following commands: + +#### Maven + +```console +$ git clone https://github.com/okteto/java-maven-getting-started +$ cd java-maven-getting-started +``` + +#### Gradle + +```console +$ git clone https://github.com/okteto/java-gradle-getting-started +$ cd java-gradle-getting-started +``` + +At the root of the directory, you'll find the `okteto.yaml` file. This describes how to [build](reference/manifest.mdx#build-object-optional) and [deploy](reference/manifest.mdx#deploy-string-optional) the Node Sample App. + +#### Maven + +``` +build: + hello-world: + image: okteto.dev/java-maven-hello-world:1.0.0 + context: . +deploy: + - kubectl apply -f k8s.yml +``` + +#### Gradle + +``` +build: + hello-world: + image: okteto.dev/java-gradle-hello-world:1.0.0 + context: . +deploy: + - kubectl apply -f k8s.yml +``` + +Deploy your development environment by executing: + +```console +$ okteto deploy --build +``` + +#### Maven + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/java-maven-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +[+] Building 5.9s (11/11) FINISHED + ... + ✓ Image 'registry.cloud.okteto.net/cindy/java-maven-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'java-maven-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +#### Gradle + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/java-gradle-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +[+] Building 5.9s (11/11) FINISHED + ... + ✓ Image 'registry.cloud.okteto.net/cindy/java-gradle-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'java-gradle-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +Log into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) and click on the URL of the application: + +Okteto Cloud UI Java + +Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto Cloud will [automatically create them](cloud/ssl.mdx) for you when you deploy your application. Cool no 😎? + +## Step 2: Activate your development container + +The [dev](reference/manifest.mdx#dev-object-optional) section defines how to activate a development container for the Java + +#### Maven + +``` +dev: + hello-world: + image: okteto/maven:3 + command: bash + sync: + - .:/usr/src/app + forward: + - 5005:5005 + volumes: + - /root/.m2 +``` + +#### Gradle + +``` +dev: + hello-world: + image: okteto/gradle:6.5 + command: bash + sync: + - .:/usr/src/app + forward: + - 5005:5005 + volumes: + - /home/gradle/.gradle +``` + +The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: +- `image`: the image used by the development container. More information on development images [here](reference/development-environments.mdx) +- `command`: the start command of the development container +- `sync`: the folders that will be synchronized between your local machine and the development container +- `forward`: a list of ports to forward from your development container +- `volumes`: a list of paths in your development container to be mounted as persistent volumes. This is useful to persist the maven/gradle caches. + +Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. +This is useful to avoid synchronizing binaries, build artifacts, or git metadata. + +## Step 3: Activate your development container + +Next, execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Namespace: cindy + Name: hello-world + Forward: 5005 -> 5005 + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application by running the following command: + +#### Maven + +```console +default:hello-world app> mvn spring-boot:run +``` + +#### Gradle + +```console +default:hello-world app> gradle bootRun +``` + +The first time you run the application, Maven/Gradle will compile your application. Wait for this process to finish. + +Go back to the browser and reload the page to test that your application is running. + +## Step 4: Develop directly on Okteto Cloud + +Open `src/main/java/com/okteto/helloworld/RestHelloWorld.java` in your favorite local IDE and modify the response message on line 11 to be *Hello world from Okteto!*. Save your changes. + +```java +package com.okteto.helloworld; + +import org.springframework.web.bind.annotation.GetMapping; +import org.springframework.web.bind.annotation.RestController; + +@RestController +public class RestHelloWorld { + + @GetMapping("/") + public String sayHello() { + return "Hello world from Okteto!"; + } +} +``` + +Your IDE will auto compile only the necessary `*.class` files which will be synchronized by Okteto to your application in Okteto Cloud. Take a look at the development container shell and notice how the changes are detected by Spring Boot and automatically hot reloaded. + +> Import the `spring-boot-devtools` dependency to automatically restart your Java application whenever a file is changed. + +Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! + +## Step 5: Debug directly on Okteto Cloud + +Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in Eclipse, one of the most popular IDEs for Java development. + +> Add the following JVM arguments in the Gradle/Maven configuration files to enable remote debugging in your Java application: +> +> `-agentlib:jdwp=transport=dt_socket,server=y,suspend=n,address=5005` + +Open the _Debug configuration_ dialog, add a new Remote Java Application debug configuration, and point it to `localhost:5005`: + +debugging in Okteto with Java + +Click the Debug button to start a debugging session. Add a breakpoint on `src/main/java/es/okteto/helloworld/RestHelloWorld.java`, line 11. Go back to the browser and reload the page. The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... + +breakpoint in Java + +Your code is executing in Okteto Cloud, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +> Okteto lets you develop your applications directly on Kubernetes. This way you can: +> - Eliminate integration issues by developing in a realistic environment +> - Test your application end to end as fast as you type code +> - No more CPU cycles wasted in your machine. Develop at the speed of the cloud! + +Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. diff --git a/versioned_docs/version-1.5/samples/more.mdx b/versioned_docs/version-1.5/samples/more.mdx new file mode 100644 index 000000000..e77d92b9a --- /dev/null +++ b/versioned_docs/version-1.5/samples/more.mdx @@ -0,0 +1,12 @@ +--- +title: Learn more about Okteto in our samples repository +description: Learn more about Okteto in our samples repository +sidebar_label: And More... +id: more +--- + +Okteto makes it easier to develop Cloud Native applications of all shapes and forms. + +Take a look at [our samples repository](https://github.com/okteto/samples) to see more examples of how to develop applications directly in your Kubernetes cluster with different programming languages, frameworks, and deployment tools. + +Are we missing your favorite framework or programming language? [File an issue](https://github.com/okteto/samples/issues/new) and let us know! \ No newline at end of file diff --git a/versioned_docs/version-1.5/samples/node.mdx b/versioned_docs/version-1.5/samples/node.mdx new file mode 100644 index 000000000..03c4b6818 --- /dev/null +++ b/versioned_docs/version-1.5/samples/node.mdx @@ -0,0 +1,203 @@ +--- +title: Getting Started on Okteto Cloud with Node.js +description: This tutorial will show you how to develop a Node.js sample application +sidebar_label: Node.js +id: node +--- + +import Image from '@theme/Image'; + +[Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) gives instant access to secure Kubernetes namespaces to enable developers to code, build, and run cloud-native applications entirely in the cloud. + +This tutorial will show you how to develop and debug a Node.js sample application running in Okteto Cloud. + +## Prerequisites + +- Install the latest version of the Okteto CLI. Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Deploy the Node.js Sample App + +Get a local version of the Node.js Sample App by executing the following commands: + +```console +$ git clone https://github.com/okteto/node-getting-started +$ cd node-getting-started +``` + +At the root of the directory, you'll find the `okteto.yaml` file. This describes how to [build](reference/manifest.mdx#build-object-optional) and [deploy](reference/manifest.mdx#deploy-string-optional) the Node Sample App. + +``` +build: + hello-world: + image: okteto.dev/node-hello-world:1.0.0 + context: . +deploy: + - kubectl apply -f k8s.yml +``` + +Deploy your development environment by executing: + +```console +$ okteto deploy --build +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/node-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +[+] Building 5.9s (11/11) FINISHED + ... + ✓ Image 'registry.cloud.okteto.net/cindy/node-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'node-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +Log into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) and click on the URL of the application: + +Okteto Cloud UI Node.js + +Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto Cloud will [automatically create them](cloud/ssl.mdx) for you when you deploy your application. Cool no 😎? + +## Step 2: Activate your development container +The [dev](reference/manifest.mdx#dev-object-optional) section defines how to activate a development container for the Node Sample App: +``` +dev: + hello-world: + command: bash + sync: + - .:/usr/src/app + forward: + - 9229:9229 +``` +The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: +- `command`: the start command of the development container. +- `sync`: the folders that will be synchronized between your local machine and the development container. +- `forward`: a list of ports to forward from your development container to localhost in your machine. This is needed to configure the Node debugger. + +Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. +This is useful to avoid synchronizing binaries, build artifacts, git metadata, or dependencies like the `node_modules` folder. + +Next, execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Namespace: cindy + Name: hello-world + Forward: 9229 -> 9229 + + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application in hot-reload mode by running the following command: + +```console +cindy:hello-world app> npm run start +``` + +```console +> node-getting-started@1.0.0 start /usr/src/app +> nodemon index.js + +[nodemon] 2.0.18 +[nodemon] to restart at any time, enter `rs` +[nodemon] watching path(s): *.* +[nodemon] watching extensions: js,mjs,json +[nodemon] starting `node index.js` +Starting hello-world server... +``` + +Go back to the browser and reload the page to test that your application is running. + +## Step 3: Develop directly on Okteto Cloud + +Open the `index.js` file in your favorite local IDE and modify the response message on line 5 to be *Hello world from the cluster!*. Save your changes. + +```javascript + res.send('Hello world from the cluster!'); +``` + +Okteto will synchronize your changes to your development container. +Take a look at the development container shell and notice how the changes are detected by `nodemon` and automatically hot reloaded. + +```console +[nodemon] restarting due to changes... +[nodemon] starting `node index.js` +Starting hello-world server... +``` + +Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! + +## Step 4: Debug directly on Okteto Cloud + +Okteto enables you to debug your applications directly from your favorite IDE. +Let's take a look at how that works in VS Code, one of the most popular IDEs for Node development. +If you haven't done it yet, install the Node.js extension available from Visual Studio marketplace. + +Cancel the execution of `nodemon index.js` from the development container shell by pressing `ctrl + c`. +Rerun your application in debug mode: + +```console +cindy:hello-world app> npm run debug +``` + +```console +Debugger listening on ws://0.0.0.0:9229/73d8d793-b0c3-4310-86ee-3a42938a5df1 +For help, see: https://nodejs.org/en/docs/inspector +``` + +Open the _Debug_ extension and run the *Connect to okteto* debug configuration (or press the F5 shortcut): + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Connect to okteto", + "type": "node", + "request": "attach", + "address": "localhost", + "port": 9229, + "localRoot": "${workspaceFolder}", + "remoteRoot": "/usr/src/app", + "skipFiles": [ + "/**" + ] + }, + ] +} +``` + +> You should be replacing the value of `remoteRoot` with wherever your application code is. + +Add a breakpoint on `index.js`, line 5. Go back to the browser and reload the page. +The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... + +breakpoint in Node.js + +Your code is running in Okteto Cloud, but you can debug it from your local machine without any extra services or tools. +Pretty cool no? 😉 + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +> Okteto lets you develop your applications directly on Kubernetes. This way you can: +> - Eliminate integration issues by developing on a realistic environment +> - Test your application end to end as fast as you type code +> - No more CPU cycles wasted in your machine. Develop at the speed of the cloud! + +Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. diff --git a/versioned_docs/version-1.5/samples/php.mdx b/versioned_docs/version-1.5/samples/php.mdx new file mode 100644 index 000000000..23f348551 --- /dev/null +++ b/versioned_docs/version-1.5/samples/php.mdx @@ -0,0 +1,162 @@ +--- +title: Getting Started on Okteto Cloud with PHP +description: This tutorial will show you how to create an account in Okteto Cloud and how to develop a PHP sample application +sidebar_label: PHP +id: php +--- + +import Image from '@theme/Image'; + +[Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) gives instant access to secure Kubernetes namespaces to enable developers to code, build, and run Kubernetes applications entirely in the cloud. + +This tutorial will show you how to create an account in Okteto Cloud and how to develop a PHP sample application. + +## Prerequisites + +- Install the latest version of the Okteto CLI. Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure Access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Deploy the PHP Sample App + +Get a local version of the PHP Sample App by executing the following commands: + +```console +$ git clone https://github.com/okteto/php-getting-started +$ cd php-getting-started +``` + +At the root of the directory, you'll find the `okteto.yaml` file. This describes how to [build](reference/manifest.mdx#build-object-optional) and [deploy](reference/manifest.mdx#deploy-string-optional) the Php Sample App. + +``` +build: + hello-world: + image: okteto.dev/php-hello-world:1.0.0 + context: . + hello-world-dev: + context: . + target: dev +deploy: + - kubectl apply -f k8s.yml +``` + +Deploy your development environment by executing: + +```console +$ okteto deploy --build +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/php-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +[+] Building 5.9s (11/11) FINISHED + ... + ✓ Image 'registry.cloud.okteto.net/cindy/php-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'php-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +Open your browser and go to the URL of the application. You can get the URL by logging into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) and clicking on the application's endpoint: + +Okteto Cloud UI PHP + +Did you notice that you're accessing your application through an HTTPS endpoint? This is because Okteto Cloud will [automatically create them](cloud/ssl.mdx) for you when you deploy your application. Cool no 😎? + +## Step 2: Activate your development container +The [dev](reference/manifest.mdx#dev-object-optional) section defines how to activate a development container for the Php Sample App: +``` +dev: + hello-world: + image: ${OKTETO_BUILD_HELLO_WORLD_DEV_IMAGE} + command: bash + sync: + - .:/app + reverse: + - 9000:9000 + volumes: + - /root/.composer/cache +``` + +The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: +- `image`: the image used by the development container. More information on development images [here](reference/development-environments.mdx) and [dynamic value for the tag](reference/manifest.mdx#build-object-optional) +- `command`: the start command of the development container. +- `sync`: the folders that will be synchronized between your local machine and the development container. +- `reverse`: a list of ports to reverse forward from your development container to your local machine +- `volumes`: a list of paths in your development container to be mounted as persistent volumes. For example, this is useful to persist the Composer cache. + +Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. +This is useful to avoid synchronizing binaries, build artifacts, or git metadata. + +Next, execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Namespace: cindy + Name: hello-world + Reverse: 9000 <- 9000 + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application by running the following command: + +```console +cindy:hello-world app> php -S 0.0.0.0:8080 +``` + +```console +[Tue Jul 5 21:04:55 2022] PHP 8.2.0 Development Server (http://0.0.0.0:8080) started +``` + +Go back to the browser, and reload the page to test that your application is running. + +## Step 3: Develop directly in Okteto Cloud + +Open the `index.php` file in your favorite local IDE and modify the response message on line 2 to be *Hello world from the cluster!*. Save your changes. + +```php + If this is the first time you debug this application, the IDE will ask you to confirm the source mapping configuration. Verify the values and click `ok` to continue. + +At this point, you're able to inspect the request object, the current values of everything, the contents of `$_SERVER` variable, etc. + +debugging in Okteto Cloud with PHP + +Your code is executing in Okteto Cloud, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +> Okteto lets you develop your applications directly in Kubernetes. This way you can: +> - Eliminate integration issues by developing in a realistic environment +> - Test your application end to end as fast as you type code +> - No more CPU cycles wasted in your machine. Develop at the speed of the cloud! + +Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. diff --git a/versioned_docs/version-1.5/samples/python.mdx b/versioned_docs/version-1.5/samples/python.mdx new file mode 100644 index 000000000..1f7e8423f --- /dev/null +++ b/versioned_docs/version-1.5/samples/python.mdx @@ -0,0 +1,205 @@ +--- +title: Getting Started on Okteto Cloud with Python +description: This tutorial will show you how to develop a Python sample application +sidebar_label: Python +id: python +--- + +import Image from '@theme/Image'; + +[Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) gives instant access to secure Kubernetes namespaces to enable developers to code, build, and run Kubernetes applications entirely in the cloud. + +This tutorial will show you how to develop and debug a Python sample application running in Okteto Cloud. + +## Prerequisites + +- Install the latest version of the Okteto CLI. Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure Access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Deploy the Python Sample App + +Get a local version of the Python Sample App by executing the following commands: + +```console +$ git clone https://github.com/okteto/python-getting-started +$ cd python-getting-started +``` + +At the root of the directory, you'll find the `okteto.yaml` file. This describes how to [build](reference/manifest.mdx#build-object-optional) and [deploy](reference/manifest.mdx#deploy-string-optional) the Python Sample App. + +``` +build: + hello-world: + image: okteto.dev/python-hello-world:1.0.0 + context: . +deploy: + - kubectl apply -f k8s.yml +``` + +Deploy your development environment by executing: + +```console +$ okteto deploy --build +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/python-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +[+] Building 5.9s (11/11) FINISHED + ... + ✓ Image 'registry.cloud.okteto.net/cindy/python-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'python-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +Log into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) and click on the URL of the application: + +Okteto Cloud UI Python + +Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto Cloud will [automatically create them](cloud/ssl.mdx) for you when you deploy your application. Cool no 😎? + +## Step 2: Activate your development container +The [dev](reference/manifest.mdx#dev-object-optional) section defines how to activate a development container for the Python Sample App: +``` +dev: + hello-world: + command: bash + environment: + - FLASK_ENV=development + sync: + - .:/usr/src/app + reverse: + - 9000:9000 + volumes: + - /root/.cache/pip +``` +The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: +- `command`: the start command of the development container. +- `sync`: the folders that will be synchronized between your local machine and the development container. +- `reverse`: a list of ports to reverse forward from your development container to your local machine +- `volumes`: a list of paths in your development container to be mounted as persistent volumes. This is useful to persist the pip cache. + +Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. +This is useful to avoid virtual environments, build artifacts, or git metadata. + +Next, execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Namespace: cindy + Name: hello-world + Reverse: 9000 <- 9000 + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application in development mode by running the following command: + +```console +cindy:hello-world app> python app.py +``` + +``` +Starting hello-world server... + * Serving Flask app "app" (lazy loading) + * Environment: development + * Debug mode: on + * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit) + ``` + +Go back to the browser and reload the page to test that your application is running. + +## Step 3: Develop directly on Okteto Cloud + +Open the `app.py` file in your favorite local IDE and modify the response message on line 7 to be *Hello world from the cluster!*. +Save your changes. + +```python +@app.route('/') +def hello_world(): + return 'Hello World from the cluster!' +} +``` + +Okteto will synchronize your changes to your development container. +Flask's auto-reloader will detect the changes automatically and restart the application with the new code. + +```console + * Detected change in '/usr/src/app/app.py', reloading + * Restarting with stat +Starting hello-world server... + * Debugger is active! + * Debugger PIN: 308-916-374 +``` + +Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! + +## Step 4: Debug directly in Okteto Cloud + +Okteto enables you to debug your applications directly from your favorite IDE. +Let's take a look at how that works in one of python's most popular IDE's, [PyCharm](https://www.jetbrains.com/pycharm/). + +> For VS Code users, this [document](https://code.visualstudio.com/docs/python/debugging#_debugging-by-attaching-over-a-network-connection) explains how to configure the debugger with `debugpy`. + +First, open the project in PyCharm and remove the comments on `app.py` line `20`. + +```python +if __name__ == '__main__': + print('Starting hello-world server...') + # comment out to use Pycharm's remote debugger + attach() + + app.run(host='0.0.0.0', port=8080) +``` + +Second, launch the [Remote Debug Server](https://www.jetbrains.com/help/pycharm/remote-debugging-with-product.html) by clicking on the Debug button on the top right. +Ensure that the Debug Tool Window shows the `Waiting for process connection...` message. This message will be shown until you launch your app on the development container shell and it connects to the Debug Server. + +```console +Starting hello-world server... + * Serving Flask app "app" (lazy loading) + * Environment: development + * Debug mode: on + * Running on http://0.0.0.0:8080/ (Press CTRL+C to quit) + * Restarting with stat +Starting hello-world server... +Connecting to debugger... +``` + +On your local machine, switch to the Debug Tool Window. Once the app connects it will show the connection to the pydev debugger. +Press the `resume` button to let the execution continue. + +debugging with Python + +Add a breakpoint on `app.py`, line 10. Go back to the browser and reload the page. + +The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc. + +breakpoint in Python + +Your code is executing in Okteto Cloud, but you can debug it from your local machine without any extra services or tools. +Pretty cool no? 😉 + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +> Okteto lets you develop your applications directly on Kubernetes. This way you can: +> - Eliminate integration issues by developing in a realistic environment +> - Test your application end to end as fast as you type code +> - No more CPU cycles wasted in your machine. Develop at the speed of the cloud! + +Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. diff --git a/versioned_docs/version-1.5/samples/ruby.mdx b/versioned_docs/version-1.5/samples/ruby.mdx new file mode 100644 index 000000000..165e6e436 --- /dev/null +++ b/versioned_docs/version-1.5/samples/ruby.mdx @@ -0,0 +1,188 @@ +--- +title: Getting Started on Okteto Cloud with Ruby +description: This tutorial will show you how to create an account in Okteto Cloud and how to develop a Ruby sample application +sidebar_label: Ruby +id: ruby +--- + +import Image from '@theme/Image'; + +[Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) gives instant access to secure Kubernetes namespaces to enable developers to code, build, and run Kubernetes applications entirely in the cloud. + +This tutorial will show you how to create an account in Okteto Cloud and how to develop a Ruby sample application. + +## Prerequisites + +- Install the latest version of the Okteto CLI. Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure Access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Deploy the Ruby Sample App + +Get a local version of the Ruby Sample App by executing the following commands: + +```console +$ git clone https://github.com/okteto/ruby-getting-started +$ cd ruby-getting-started +``` + +At the root of the directory, you'll find the `okteto.yaml` file. This describes how to [build](reference/manifest.mdx#build-object-optional) and [deploy](reference/manifest.mdx#deploy-string-optional) the Python Sample App. + +``` +build: + hello-world: + image: okteto.dev/ruby-hello-world:1.0.0 + context: . +deploy: + - kubectl apply -f k8s.yml +``` + +Deploy your development environment by executing: + +```console +$ okteto deploy --build +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Building image for service 'hello-world' + i Building the image 'okteto.dev/ruby-hello-world:1.0.0' in tcp://buildkit.cloud.okteto.net:1234... +[+] Building 5.9s (11/11) FINISHED + ... + ✓ Image 'registry.cloud.okteto.net/cindy/ruby-hello-world:1.0.0' successfully pushed + i Running kubectl apply -f k8s.yml +deployment.apps/hello-world created +service/hello-world created +ingress.networking.k8s.io/hello-world created + ✓ Development environment 'ruby-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +Log into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs) and click on the URL of the application: + +Okteto Cloud UI Ruby + +Did you notice that you're accessing your application through an HTTPs endpoint? This is because Okteto Cloud will [automatically create them](cloud/ssl.mdx) for you when you deploy your application. Cool no 😎? + +## Step 2: Activate your development container +The [dev](reference/manifest.mdx#dev-object-optional) section defines how to activate a development container for the Ruby Sample App: +``` +dev: + hello-world: + command: bash + sync: + - .:/opt/app/ + forward: + - 1234:1234 + volumes: + - /usr/local/bundle/cache +``` +The `hello-world` key matches the name of the hello world Deployment. The meaning of the rest of fields is: +- `command`: the start command of the development container. +- `sync`: the folders that will be synchronized between your local machine and the development container. +- `forward`: a list of ports to forward from your development container to localhost in your machine. This is needed to configure the Ruby debugger. +- `volumes`: a list of paths in your development container to be mounted as persistent volumes. For example, this is useful to persist the bundle cache. + +Also, note that there is a `.stignore` file to indicate which files shouldn't be synchronized to your development container. +This is useful to avoid synchronizing binaries, build artifacts or git metadata. + + +Next, execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Namespace: cindy + Name: hello-world + Forward: 1234 -> 1234 + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application in hot-reload mode by running the following command: + +```console +cindy:hello-world app> ruby app.rb +``` + +```console +[2022-07-04 16:50:53] INFO WEBrick 1.6.1 +[2022-07-04 16:50:53] INFO ruby 2.7.6 (2022-04-12) [x86_64-linux] +== Sinatra (v2.0.8.1) has taken the stage on 8080 for production with backup from WEBrick +[2022-07-04 16:50:53] INFO WEBrick::HTTPServer#start: pid=79 port=8080 +``` + +Go back to the browser and reload the page to test that your application is running. + +## Step 3: Develop directly in Okteto Cloud + +Open the `app.rb` file in your favorite local IDE and modify the response message on line 7 to be *Hello world from the cluster!*. Save your changes. + +```ruby +get "/" do + message = "Hello world from the cluster!" + message +end +``` + +Okteto will synchronize your changes to your development container in Kubernetes and Sinatra automatically detects them and reloads your application. + +Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! + +## Step 4: Debug directly in Okteto Cloud + +Okteto enables you to debug your applications directly from your favorite IDE. Let's take a look at how that works in VS Code, one of the most popular IDEs for Ruby development. If you haven't done it yet, install the [Ruby extension](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby) available from Visual Studio marketplace. This extension comes with debug definitions covering the default `ruby-debug-ide` client setup. + +Now, cancel the execution of `ruby app.rb` from the development container shell by pressing `ctrl + c`. Rerun your application in debug mode: + +```console +cindy:hello-world app> rdebug-ide --host 0.0.0.0 app.rb +``` + +```console +Fast Debugger (ruby-debug-ide 0.7.0, debase 0.2.4.1, file filtering is supported) listens on 0.0.0.0:1234 +``` + +Open the _Run_ view in VS Code and run the *Connect to okteto* debug configuration (or press the F5 shortcut): + +```json +{ + "version": "0.2.0", + "configurations": [ + { + "name": "Connect to okteto", + "type": "Ruby", + "request": "attach", + "remotePort": "1234", + "remoteHost": "localhost", + "remoteWorkspaceRoot": "/opt/app", + "cwd": "${workspaceRoot}", + } + ] +} +``` + +> You should be replacing the value of `remoteWorkspaceRoot` with wherever your application code is. + +Add a breakpoint on `app.rb`, line 8. Go back to the browser and reload the page. The execution will halt at your breakpoint. You can then inspect the request, the available variables, etc... + +debugging in Okteto with Ruby + +Your code is executing in Okteto Cloud, but you can debug it from your local machine without any extra services or tools. Pretty cool no? 😉 + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +> Okteto lets you develop your applications directly in Kubernetes. This way you can: +> - Eliminate integration issues by developing in a realistic environment +> - Test your application end to end as fast as you type code +> - No more CPU cycles wasted in your machine. Develop at the speed of the cloud! + +Find more advanced samples with Okteto in [this repository](https://github.com/okteto/samples) or [join our community](https://community.okteto.com) to ask questions and share your feedback. diff --git a/versioned_docs/version-1.5/self-hosted.mdx b/versioned_docs/version-1.5/self-hosted.mdx new file mode 100644 index 000000000..bed1644ba --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted.mdx @@ -0,0 +1,25 @@ +--- +title: Okteto Self-Hosted +description: Build better applications by developing and testing your code directly on your Kubernetes infrastructure +sidebar_label: Intro +id: self-hosted +--- + +Okteto is a development platform for Kubernetes applications. Build better applications by developing and testing your code directly in your own Kubernetes infrastructure. Give your team the power of the [Okteto Development Platform](index.md), with the control and flexibility of running in your Kubernetes infrastructure. + +With Okteto your team can: + +- Deploy your development environments with the [Okteto CLI](getting-started.mdx) or from your [Git Repositories](cloud/deploy-from-git.mdx). +- Configure [Secrets](cloud/secrets.mdx) and prevent secure credentials from being stored in version control. +- Expose your development environments via [Automatic HTTPs Endpoints](cloud/ssl.mdx) for your services, [Private Endpoints](cloud/private-endpoints.mdx) to restrict access, and [Custom Domain Names](cloud/custom-domains.mdx). +- Build your images directly in the cloud using the [Okteto Build Service](cloud/build.mdx). +- Push your container images in the [Okteto Registry](cloud/registry.mdx). +- Create secure Kubernetes [Namespaces](cloud/namespaces.mdx) with one click. +- Download your [Kubernetes Credentials](cloud/credentials.mdx) to access your namespaces with `kubectl`, `helm`, or any other CLI tool. +- Collaborate by [sharing](cloud/namespaces.mdx#share-your-namespace) your namespaces with your teammates +- Keep your infrastructure under control with the Okteto [Garbage Collector](administration/cleanup.mdx) and the [Okteto Autoscaler](self-hosted/administration/configuration.mdx#autoscaler) + +[** Okteto is free for small teams. Click here to get started**](self-hosted/install/overview.mdx). + +Questions? [Talk to us](https://okteto.com/#talktous) to learn more about how Okteto can help accelerate your team. + diff --git a/versioned_docs/version-1.5/self-hosted/administration/certificates.mdx b/versioned_docs/version-1.5/self-hosted/administration/certificates.mdx new file mode 100644 index 000000000..cc81370f2 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/administration/certificates.mdx @@ -0,0 +1,73 @@ +--- +title: Bringing Your Own Certificates +description: Use your own certificates with Okteto +sidebar_label: Bring your own Certificates +id: certificates +--- + +## Bring your own Wildcard Certificate + +By default, Okteto will create a self-signed wildcard certificate for your cluster. This certificate is used to secure communication to the Okteto dashboard, the build service, the registry service, and to all the applications that use [Automatic SSL Endpoints](https://okteto.com/docs/cloud/ssl/). + +In a production environment, you should use your own certificates rather than let Okteto create a self-signed wildcard certificate for you. You can configure this via the `wildcardCertificate` configuration key in your Helm configuration file. + +To start, you need the private and public keys of your certificate. The certificate must be a PEM-encoded X.509 certificate in PKCS1 format, with `*.SUBDOMAIN` as its `Subject Alternative Name`. + +Import the secret into your kubernetes cluster by running the command below: + +``` +kubectl create secret tls ${CERT_NAME} --key ${KEY_FILE} --cert ${CERT_FILE} --namespace okteto +``` + +After you create the secret, add the following to your Helm configuration file to tell Okteto and NGINX to use your certificate. + +``` +wildcardCertificate: + create: false + name: your-ssl-certificate-secret + +ingress-nginx: + controller: + extraArgs: + default-ssl-certificate: $(POD_NAMESPACE)/your-ssl-certificate-secret +``` + +If you are using [cert-manager](https://cert-manager.io/), you need to use a [DNS01](https://cert-manager.io/docs/configuration/acme/dns01/#delegated-domains-for-dns01) auth method in your [Issuer](https://cert-manager.io/docs/concepts/issuer/). +Check the list of supported providers [here](https://cert-manager.io/docs/configuration/acme/dns01/) for more information. +There are community guides for the following Cloud Providers: + +- [Amazon Route53](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-aws-route53/273/2) +- [Google Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-google-cloud-dns/274/2) +- [Azure Cloud DNS](https://community.okteto.com/t/how-do-i-configure-okteto-with-cert-manager-and-azure-cloud-dns/275/2) + +Finally, [install or upgrade](self-hosted/install/deployment.mdx) your Okteto installation for the new configuration to be applied. + +## Bring your own Certificate Authority + +By default, Okteto will trust a certificate issued by any well-know certificate authority. If your certificate is self-signed, issued by a new certificate authority, or issued by a private certificate authority, you'll need to import your certificate authority's public key. + +First import your certificate authority by running the command below: + +``` +kubectl create secret generic ${CA_NAME} --from-file=ca.crt=${CA_FILE} --namespace okteto +``` + +After you create the secret, add the following to your Helm configuration file to tell Okteto to use your certificate authority. + +``` +wildcardCertificate: + create: false + name: your-ssl-certificate-secret + privateCA: + enabled: true + secret: + name: your-ca-secret + key: ca.crt + +ingress-nginx: + controller: + extraArgs: + default-ssl-certificate: $(POD_NAMESPACE)/your-ssl-certificate-secret +``` + +Finally, [install or upgrade](self-hosted/install/deployment.mdx) your Okteto installation for the new configuration to be applied. diff --git a/versioned_docs/version-1.5/self-hosted/administration/configuration.mdx b/versioned_docs/version-1.5/self-hosted/administration/configuration.mdx new file mode 100644 index 000000000..d8de7de92 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/administration/configuration.mdx @@ -0,0 +1,1218 @@ +--- +title: Configuration Settings +description: List of configuration settings for Okteto +id: configuration +--- + +## General Settings + +### email + +The email of the application owner. + +```yaml +email: "admin@example.com" +``` + +### cluster + +- `endpoint`: The public endpoint of your Kubernetes cluster. It will be used by Okteto when generating `Kubeconfig` credentials for your users. + +```yaml +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. + +```yaml +license: XXXXX +``` + +Want to use Okteto with a bigger team? [Let's talk](https://okteto.com/#talktous) + +> You can also use a [secret](self-hosted/install/deployment.mdx#cloud-provider-secret) to store the license. + +### subdomain + +The domain (or subdomain) managed by Okteto. + +Your Okteto instance will be available at `okteto.$SUBDOMAIN`. All ingresses created by okteto will use it as well (e.g. https://app-$NAMESPACE.$SUBDOMAIN) + +```yaml +subdomain: "example.com" +``` + +After installation, we recommend that you create a DNS entry for `*.$SUBDOMAIN`, pointing to the public address of your load balancer. + +### auth + +Okteto supports using Bitbucket, GitHub, Google, or OpenID Connect as authentication providers. + +> You can also use a [secret](self-hosted/install/deployment.mdx#cloud-provider-secret) to store the sensitive part of these credentials. + +#### Bitbucket + +Follow Bitbucket's official documentation on [how to create an OAuth Consumer](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/). + +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. + +```yaml +auth: + bitbucket: + enabled: true + clientId: OAauth Consumer Key + clientSecret: OAauth Consumer Secret + workspace: my-workspace +``` + +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](self-hosted/administration/configuration.mdx#creating-the-github-app). 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](https://developer.github.com/apps/building-oauth-apps/creating-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. + +```yaml +auth: + github: + enabled: true + clientId: clientID + clientSecret: clientSecret + organization: my-org +``` + +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](https://support.google.com/cloud/answer/6158849?hl=en). + +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. + +```yaml +auth: + google: + enabled: true + clientId: clientid.apps.googleusercontent.com + clientSecret: clientSecret + allowDomains: + - example.com +``` + +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: + +- [Azure Active Directory](self-hosted/guides/azure-active-directory/index.mdx) +- [Gitlab](self-hosted/guides/gitlab/index.mdx) +- [Okta](self-hosted/guides/okta/index.mdx) + + +> Are we missing your favorite identity provider? Open a feature request in the [Okteto Community](https://community.okteto.com/t/about-the-feature-requests-category/28) 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. + +```yaml +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 +``` + +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](https://openid.net/specs/openid-connect-core-1_0.html#UserInfo) in order to be used with Okteto. This authentication option follows the OpenID standard, and it has been validated with Okta, PingIdentity, and GitLab. + +### cloud + +Okteto integrates with different cloud providers to store the [Okteto Registry](cloud/registry.mdx) images. + +> The sensitive part of the credentials are not included in the configuration file. Instead, it is provided to Okteto via [a secret](self-hosted/install/deployment.mdx#cloud-provider-secret). + +#### Azure + +Use this to use Azure Storage to store your private images. + +```yaml +cloud: + provider: + azure: + enabled: true + storage: + container: "Storage Container Name" + accountName: "Storage Account Name" +``` + +The storage setting will be used by the registry to pull and push images (if [using cloud storage](#registry)). This needs to be created before installing Okteto. + +#### AWS + +Use this to use S3 to store your private images. + +The bucket will be used by the registry to pull and push images (if [using cloud storage](#registry)). This needs to be created before installing Okteto. + +##### IAM User + +```yaml +cloud: + provider: + aws: + enabled: true + bucket: "Bucket Name" + region: "AWS region" + iam: + enabled: true + accessKeyID: "IAM Access Key" +``` + +##### IAM Role for Service Account (IRSA) + +```yaml +cloud: + provider: + aws: + enabled: true + bucket: "Bucket Name" + region: "AWS region" + iam: + enabled: false +registry: + serviceAccount: + annotations: + eks.amazonaws.com/role-arn: 'arn:aws:iam::111122223333:role/okteto-registry-role-name' +``` + +#### Digitalocean + +Use this to use DigitalOcean Spaces to store your private images. + +```yaml +cloud: + provider: + digitalocean: + enabled: true + space: + name: + accessKeyID: +``` + +The space settings will be used by the registry to pull and push images (if [using cloud storage](#registry)). This needs to be created before installing Okteto. + +#### GCP + +Use this to use Google Cloud Storage to store your private images. + +The bucket settings will be used by the registry to pull and push images (if [using cloud storage](#registry)). This needs to be created before installing Okteto. + +##### Service Account Key (JSON) + +```yaml +cloud: + provider: + gcp: + enabled: true + bucket: "Bucket Name" + project: "Project ID" +``` + +##### Workload Identity + +```yaml +cloud: + provider: + gcp: + enabled: true + bucket: "Bucket Name" + project: "Project ID" + workloadIdentity: + enabled: true +registry: + serviceAccount: + annotations: + iam.gke.io/gcp-service-account: 'GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com' +``` + +#### BYO + +Use this if you're using a provider not currently supported by Okteto. + +```yaml +cloud: + provider: + byo: + enabled: true +``` + +When using `byo` you'll need to [configure your registry](self-hosted/administration/configuration.mdx#registry) to use a persistent volume for storage. + +```yaml +registry: + storage: + filesystem: + enabled: true + persistence: + enabled: true + size: 400Gi + cloud: + enabled: false +``` + +#### Advanced Cloud Scenarios + +It is possible to use separate cloud providers for DNS than for storage if needed. [Reach out to support](https://okteto.com/support), we're always happy to help! + +## 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. + +```yaml +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. + +```yaml +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](https://kubernetes.io/docs/concepts/workloads/controllers/statefulset/#pod-management-policies) of the buildkit pods. Defaults to `Parallel`. +- `replicaCount`: The number of buildkit pods. It defaults to 1. +- `resources`: The resources for the buildkit pods. +- `storage.class`: The storage class of the volume attached to every buildkit pod to persist the buildkit cache. +- `storage.size`: The size of the volume attached to every buildkit pod to persist the buildkit cache. +- `storage.cache`: The size of the buildkit cache to store image caches. It should be 30Gi smaller than `storage.size`. + +```yaml +buildkit: + port: 443 + extraEnv: + - name: NO_PROXY + value: ".example.com" + replicaCount: 1 + storage: + class: 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. +- `initContainers.privateCA.image`: InitContainer image used by the daemon pods. Defaults to `busybox` + +### 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. + +```yaml +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. + +```yaml +gc: + enabled: true + scaleToZeroPeriod: 24 + deleteNamespacePeriod: 15 + slackWebhook: +``` + +### installer + +The jobs that deploy your [development environments from Git](cloud/deploy-from-git.mdx). + +- `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](self-hosted/administration/custom-installer-image.mdx). +- `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. + + +```yaml +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 +``` + +- `buildCredentialHelpers`: Mapping of registry hostnames as keys to credential helpers as values. Disabled if `privateRegistry` is defined. Registry hostnames must be Fully Qualified Domain Names. Credential helper names must be accessible at installer job pod `$PATH` as `docker-credential-$NAME`. + +```yaml +installer: + buildCredentialHelpers: + 111122223333.dkr.ecr.eu-central-1.amazonaws.com: ecr-login +user: + serviceAccount: + annotations: + eks.amazonaws.com/role-arn: 'arn:aws:iam::111122223333:role/okteto-installer-role-name' +``` + +### 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](self-hosted/administration/configuration.mdx#ingress) section. +- `ingress.tlsSecret`: TLS secret for the registry endpoint. If empty, okteto will default to the wildcard certificate created by Okteto. +- `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. +- `storage`: The storage mechanism for the images. + - `cloud.enabled`: Set this to true if you want to store the images using your cloud provider's block storage service (e.g. S3). It will use the values defined in the [`cloud` key](#cloud). It's enabled by default. + +```yaml +registry: + extraEnv: + - name: NO_PROXY + value: ".example.com" + storage: + cloud: + enabled: true +``` + + - `filesystem`: Set this to true if you want to store the images in PVC attached to the registry. This might limit your ability to scale up the registry, depending on the type of storage you are using. You can also customize the `storageClass`, the `size` of the volume, and even attach an existing volume claim via `claimName`. + +```yaml +registry: + storage: + cloud: + enabled: false + filesystem: + enabled: true + persistence: + claimName: "" + accessMode: ReadWriteOnce + storageClass: "" + size: 40Gi +``` + +### 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. + +```yaml +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. + +```yaml +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](cloud/deploy-from-helm.mdx) available for every developer. This is disabled by default. To enable, set the `applications.repository` property to your Helm registry URL + +```yaml +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. + +```yaml +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: + +```yaml +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. + +```yaml +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`). + +```yaml +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](reference/manifest.mdx#persistentvolume-object-optional). Disabled by default. + +- `storageClass`: The storage class enforced for persistent volume claims created by `okteto up`. + +```yaml +devStorageClass: + enabled: true + storageClass: ebs-sc +``` + +There is only one exception where this storage class is overwritten. In case of having [volume snapshots feature](self-hosted/administration/volume-snapshots.mdx) 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. + +```yaml +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 Okteto API/Registry is exposed using an ingress not managed by Okteto. +- `tlsSecret`: TLS secret for the ingress created by Okteto. If empty, okteto defaults to the wildcard certificate created by Okteto. + +```yaml +ingress: + annotations: {} + oktetoIngressClass: nginx + class: nginx + forceIngressClass: false + forceIngressSubdomain: true + ip: "" + tlsSecret: "" +``` +### 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. + +```yaml +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`. + +```yaml +injectDevelopmentBinaries: + enabled: true +``` + +### namespace + +Annotation and label customizations for namespaces. +The configured annotations and labels will be applied to each namespace created by Okteto. +These annotations and labels are additional to the ones already applied by Okteto. + +- `annotations`: Annotations applied to each namespace generated by Okteto. +- `labels`: Labels applied to each namespace generated by Okteto. + +```yaml +namespace: + annotations: + custom.annotation/one: one + custom.annotation/two: two + labels: + custom.label/one: one + custom.label/two: two +``` + +### networkPolicies + +Configures [network policies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) for each namespace to isolate network traffic. +Disabled by default. + +- `ingress`: Ingress list of rules ([NetworkPolicyIngressRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#networkpolicyingressrule-v1-networking-k8s-io)) to be applied on every namespace managed by Okteto. (optional). +- `egress`: Egress list of rules ([NetworkPolicyEgressRule](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.22/#networkpolicyegressrule-v1-networking-k8s-io)) to be applied on every namespace managed by Okteto (optional). + +```yaml +networkPolicies: + enabled: false + ingress: [] + egress: [] +``` + +### podSecurityPolicy + +Decide if you want [pod security policy](https://kubernetes.io/docs/concepts/security/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: + +```yaml +apparmor.security.beta.kubernetes.io/allowedProfileNames: runtime/default +apparmor.security.beta.kubernetes.io/defaultProfileName: runtime/default +``` + +```yaml +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. + +```yaml +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. + +```yaml +overrideRegistryResolution: + enabled: true +``` + +### prepullImages + +Pre-pull the git and helm installer images in all the nodes. This requires permission to mount the docker socket. + +```yaml +prepullImages: + enabled: true +``` + +### privateRegistry + +A list of private registries and its corresponding credentials. The kubelet will use them when pulling images: + +```yaml +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](self-hosted/install/troubleshooting.mdx#private-image-registry-credentials-misconfiguration) to recover from this state. + +### pullAlways + +Forces the `PullAlways` image pull policy in the cluster. Enabled by default. + +```yaml +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. + +```yaml +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](https://kubernetes.io/docs/concepts/policy/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. + - `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](self-hosted/administration/configuration.mdx#nginx-ingress). + - `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](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) per namespace. + - `cpu`: Maximum CPU resource requests. + - `memory`: Maximum memory resource requests. + - `storage`: Maximum storage resource requests. +- `limits`: Limits the maximum [resource limits](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/#requests-and-limits) per namespace. + - `cpu`: Maximum CPU resource limits. + - `memory`: Maximum memory resource limits. + - `storage`: Maximum storage resource limits. +- `limitranges`: Configures the [limit ranges](https://kubernetes.io/docs/concepts/policy/limit-range/) 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. + - `limitRequestRatio`: If this value is different than zero, Okteto automatically sets the requests of each container to its limits divided by this value. It is useful to keep requests low in the cluster and make better usage of your infrastructure. Defaults to 1000. + - `cpu`: Default CPU resource requests. Ignored if `limitRequestRatio` is different than zero. + - `memory`: Default memory resource requests. Ignored if `limitRequestRatio` is different than zero. + - `limits`: Configures the default resource limits per container. + - `cpu`: Default CPU resource limits. + - `memory`: Default memory resource limits. + +The default values are: + +```yaml +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 + limitRequestRatio: 1000 + 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. + +```yaml +secret: + annotations: + your.custom.annotation: "10" + labels: + your.custom.label: "20" +``` + +### tolerations + +Indicates [tolerations](https://kubernetes.io/docs/concepts/scheduling-eviction/taint-and-toleration/) 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. + +```yaml +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. + +```yaml +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 + +```yaml +userPodAffinity: + enabled: true + antiAffinity: + enabled: false +``` + +### virtualServices + +When enabled, the Okteto UI will show the public endpoints associated with [Istio Virtual Services](https://istio.io/latest/docs/reference/config/networking/virtual-service/) (default: `false`). + +```yaml +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. + +```yaml +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. + +```yaml +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: + +```yaml +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](https://kubernetes.io/docs/concepts/storage/volume-snapshots/) 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. + +```yaml +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. + +```yaml +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](https://community.okteto.com/t/support-for-gke-workload-identities-for-okteto-self-hosted/39/4) to create Cloud resources as part of your Okteto Manifest `deploy` commands. + +- [Azure Workload Identity](https://azure.github.io/azure-workload-identity/docs/) +- [GKE Workload identity](https://cloud.google.com/kubernetes-engine/docs/how-to/workload-identity) +- [AWS IAM Roles for service accounts](https://docs.aws.amazon.com/eks/latest/userguide/iam-roles-for-service-accounts.html) + + +## Dependencies + +Okteto will automatically install [NGINX Ingress Controller](https://kubernetes.github.io/ingress-nginx/) as part of the default installation, using its official [Helm chart](https://kubernetes.github.io/ingress-nginx). + +### NGINX-Ingress + +Use the `ingress-nginx` keys in your configuration file to modify the configuration. + +For example, to change the number of replicas, you'd need to add the following: + +```yaml +ingress-nginx: + controller: + replicaCount: 2 +``` + +The full list of values is [available here](https://github.com/kubernetes/ingress-nginx/blob/main/charts/ingress-nginx/values.yaml). diff --git a/versioned_docs/version-1.5/self-hosted/administration/custom-installer-image.mdx b/versioned_docs/version-1.5/self-hosted/administration/custom-installer-image.mdx new file mode 100644 index 000000000..51ecfed6e --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/administration/custom-installer-image.mdx @@ -0,0 +1,51 @@ +--- +title: Custom Installer Image +description: Use a custom installer image to deploy your Development Environments +sidebar_label: Custom Installer Image for your Pipelines +id: custom-installer-image +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +You can specify a custom installer image to deploy your Development Environments. Use this if you want to use tools, frameworks, or custom configurations not included in the [default installer image](https://github.com/okteto/pipeline-runner). + +## Requirements + +To use the Custom Installer Image feature, you first need to create your own Docker image, and push it to a registry that can be accessed by your Okteto instance. + +### Defining the Custom Image + +When creating your image, we recommend extending the image from [the latest version](https://github.com/okteto/pipeline-runner/releases) of the default pipeline runner image. + +Your image can include anything that you need when deploying Development Environments for your organization. The example below shows you how to include `wget`: + +``` +FROM okteto/pipeline-runner:1.0.0 + +RUN apt-get upgrade && \ + apt-get install wget +``` + +### Build and Publish the Custom Image + +Once the image has been defined, build it and push it to your container registry. + +``` +docker build -t YOUR_COMPANY/pipeline-installer:1 +docker push YOUR_COMPANY/pipeline-installer:1 +``` + +## Configure your Custom Image + +To enable the custom image, update your `config.yaml` file with the following values, and run a [helm upgrade](https://okteto.com/docs/self-hosted/install/upgrade/#upgrade-your-okteto-enterprise-instance) to apply the new configuration. + +```yaml +installer: + runner: YOUR_COMPANY/pipeline-runner:1 +``` + +## Using the Custom Image + +Once the configuration has been applied, all the Development Environments will be deployed using your custom image. In order to help you troubleshoot any issues, the name of the image used during deployment is included in the pipeline logs. You can consult this in the Okteto dashboard. + diff --git a/versioned_docs/version-1.5/self-hosted/administration/github.mdx b/versioned_docs/version-1.5/self-hosted/administration/github.mdx new file mode 100644 index 000000000..fa8c20e5e --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/administration/github.mdx @@ -0,0 +1,120 @@ +--- +title: GitHub Integration +description: Use our GitHub Integrate so your users can access private repositories in their development environments +sidebar_label: GitHub Integration +id: github +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; +import TiersList from '@theme/TiersList'; + +You can configure Okteto to use a GitHub to authenticate your users as well as give them access to private GitHub repositories. + +There are several reasons for considering this approach including: +- Your users can select a repo from a list, instead of having to type the full repository URL. +- Give everyone on your cluster read-only access to private repositories. +- Control access to Okteto and the repositories at the Organization level, or per repository. +- The pipelines use an app-scoped token, instead of a shared user. + + +## Configuration Steps + +Setting up the GitHub integration requires several steps in both GitHub and your Okteto instance. Complete the following steps in GitHub: + +1. [Create the GitHub Application](#creating-the-github-app) +1. [Generate a private key for the GitHub App](#generating-a-private-key-for-the-github-app) + + +Complete the following steps in your Okteto Self-Hosted instance: + +1. [Adding the GitHub App Configuration to Okteto](#adding-the-github-app-configuration-to-okteto) +1. [Verify your installation](#verifying-your-installation) + +Once this configuration has been completed, your instance of Okteto will use the GitHub Application you authenticate during the clone repository step of any Okteto pipelines. + + +### Creating the GitHub App + +1. In the upper-right corner of any page in GitHub, select your `profile icon > Organizations`. +1. Click on the `settings` of the organization you want to use to create the application. +1. In the left navigation, select `Developer settings > GitHub Apps`. +1. Select `New GitHub App`. +1. Complete the following fields as follows: + - `GitHub App Name:` enter an appropriate name for your application (e.g. `okteto-$YOUR_GITHUB_ORGANIZATION`) + - `Homepage URL:` https://okteto.$SUBDOMAIN + - `Callback URL:` https://okteto.$SUBDOMAIN + - `Authorization callback URL:` https://okteto.$SUBDOMAIN/auth/callback (Necessary if you are going to use GitHub as your auth provider) +1. Uncheck the `Expire user authorization tokens` option. +1. Check the `Request user authorization (OAuth) during installation` option. +1. On the `Post Installation` section, check the `Redirect on update` option. +1. On the `Webhook` section, uncheck the `Active` option. +1. On the `Repository permissions` section, set the `Contents` permission to `Read-only`. +1. On the `Organization permissions` section, set the `Members` permission to `Read-only`. +1. On the `User permissions` section, set the `Email addresses` permission to `Read-only`. +1. On the `Where can this GitHub App be installed?` section, select the `Any account` option. This will allow your users to install the application in their own GitHub account and deploy personal repositories in your Okteto instance. +1. Press the `Create GitHub App` button. +1. On the next screen, copy the values of `App Id` and `Client Id`, you'll need to pass those to your Okteto instance in a future step. + +> See [Creating a GitHub App](https://docs.github.com/en/developers/apps/building-github-apps/creating-a-github-app) for more information on creating a GitHub App from GitHub’s Developer guide. + +### Generating a private key for the GitHub App + +After you have created the GitHub App, you will need to generate a private key for authenticating to the GitHub App. + +To generate a private key authenticating to the GitHub App: + +1. In the upper-right corner of any page in GitHub, select your `profile icon > Organizations`. +1. Click on the `settings` of the organization you want to use to create the application. +1. In the left navigation, select `Developer settings > GitHub Apps`. +1. Select the GitHub App. +1. On the `Client secrets` section, press the `Generate a new client secret` button. Copy the value and save it in a safe place, since it won't be displayed again. You'll need to pass those to your Okteto instance in a future step. +1. On the `Private keys` section (it's at the bottom of the page), press the `Generate a private key` button. A file with the private key will be saved in your computer. + + +### Adding the GitHub App Configuration to Okteto + +Add the values we generated in the previous steps to your existing [Helm configuration file](self-hosted/install/deployment.mdx#configuration-file). + +```yaml +github: + enabled: true + appId: ${YOUR_APP_ID} + clientId: ${YOUR_CLIENT_ID} + clientSecret: ${YOUR_CLIENT_SECRET} + installationUrl: https://github.com/apps/${YOUR_GITHUB_APP_NAME}/installations/new + appPrivateKey: | + -----BEGIN RSA PRIVATE KEY----- + ...... + ..... + -----END RSA PRIVATE KEY----- +``` + +> You can also [use a secret](self-hosted/install/deployment.mdx#cloud-provider-secret) to store the clientSecret and the appPrivateKey. + +- `clientID` and `clientSecret` refers to the values of the GitHub App you just created. +- `appPrivateKey` is the private key you generated. + +> You can also use the appId and clientId values of your GitHub application in the `auth.github` section of your Helm configuration file if you're using GitHub as your [authentication provider](self-hosted/install/deployment.mdx#authentication). + + +Once you have updated your Helm configuration file, run the following command to reconfigure your Okteto instance: + +``` +helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +If you're doing this as part of a fresh install, then run the following command: + +``` +helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +### Verifying your installation + +If the installation was successful, you should now see a `GitHub` option in the `Deploy from Git` dialog. + +

verify your installation

+ +When you click on it, you should see the list of repositories that you added in the previous step. [This document](cloud/private-repositories.mdx) has further information on how to deploy a private repository. diff --git a/versioned_docs/version-1.5/self-hosted/administration/images/verify-installation.png b/versioned_docs/version-1.5/self-hosted/administration/images/verify-installation.png new file mode 100644 index 000000000..88991130a Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/administration/images/verify-installation.png differ diff --git a/versioned_docs/version-1.5/self-hosted/administration/volume-snapshots.mdx b/versioned_docs/version-1.5/self-hosted/administration/volume-snapshots.mdx new file mode 100644 index 000000000..11b46f880 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/administration/volume-snapshots.mdx @@ -0,0 +1,207 @@ +--- +title: Volume Snapshots +description: Enable volume snapshots in Okteto +sidebar_label: Volume Snapshots +id: volume-snapshots +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +Volume snapshots allows you to initialize persistent volume claims with the contents of a preexisting volume snapshot. +Use volume snapshots when working with large datasets or if you want to create development environments with real data coming from your production or staging environments. +## Requirements + +To use the Volume Snapshots feature, you must install a CSI driver that supports snapshots and create the corresponding `VolumeSnapshotClass`. + +### Installing the CSI Driver + +Volume Snapshots is compatible with any CSI-compliant driver, such as: +- [Google Compute Engine Persistent Disk CSI Driver](https://cloud.google.com/kubernetes-engine/docs/how-to/persistent-volumes/gce-pd-csi-driver) +- [Amazon EBS CSI driver](https://docs.aws.amazon.com/eks/latest/userguide/ebs-csi.html) +- [DigitalOcean Block Storage CSI Driver](https://github.com/digitalocean/csi-digitalocean) + +> Note: As of February 2021, if you're using the Amazon EBS CSI driver, you'll need to install the alpha version to enable Volume Snapshots. More information is available [on their github repository](https://github.com/kubernetes-sigs/aws-ebs-csi-driver). + +We recommend you follow your vendor's installation instructions to learn more about this topic. + +### Create a VolumeSnapshotClass + +Create a `VolumeSnapshotClass` in your cluster to determine the CSI driver and `deletionPolicy` for your `VolumeSnapshots`. + +The following manifest is an example of a VolumeSnapshotClass: + + + + +```yaml +# okteto-snapshot-class.yaml +apiVersion: snapshot.storage.k8s.io/v1 +kind: VolumeSnapshotClass +metadata: + name: okteto-snapshot-class +driver: ebs.csi.aws.com +deletionPolicy: Delete +``` + + + + +```yaml +# okteto-snapshot-class.yaml +apiVersion: snapshot.storage.k8s.io/v1 +kind: VolumeSnapshotClass +metadata: + name: okteto-snapshot-class +driver: pd.csi.storage.gke.io +deletionPolicy: Delete +``` + + + + + +```yaml +# okteto-snapshot-class.yaml +apiVersion: snapshot.storage.k8s.io/v1 +kind: VolumeSnapshotClass +metadata: + name: okteto-snapshot-class +driver: dobs.csi.digitalocean.com +deletionPolicy: Delete +``` + + + + +To create the `VolumeSnapshotClass` run the following command after creating the file. + +``` +kubectl apply -f okteto-snapshot-class.yaml +``` + +### Create a StorageClass (optional) + +Optionally, you can also create a storage class. This storage class will be used by Okteto when creating the volumes. + + + + +```yaml +# okteto-snapshot-sc.yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: okteto-snapshot-sc +provisioner: ebs.csi.aws.com +reclaimPolicy: Delete +volumeBindingMode: WaitForFirstConsumer +``` + + + + +```yaml +# okteto-snapshot-sc.yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: okteto-snapshot-sc +provisioner: pd.csi.storage.gke.io +parameters: + type: pd-standard +reclaimPolicy: Delete +volumeBindingMode: WaitForFirstConsumer +``` + + + + +```yaml +# okteto-snapshot-sc.yaml +kind: StorageClass +apiVersion: storage.k8s.io/v1 +metadata: + name: okteto-snapshot-sc +provisioner: dobs.csi.digitalocean.com +reclaimPolicy: Delete +volumeBindingMode: WaitForFirstConsumer +``` + + + + +To create the `StorageClass` run the following command after creating the file. + +``` +kubectl apply -f okteto-snapshot-sc.yaml +``` + +## Enabling Volume Snapshots + +To enable Volume Snapshots on your Okteto instance, update your `config.yaml` file with the following values, and run a [helm upgrade](https://okteto.com/docs/self-hosted/install/upgrade/#upgrade-your-okteto-enterprise-instance) to apply the new configuration. + +More information on the different configuration settings [is available here](self-hosted/administration/configuration.mdx#volumesnapshots). + + + + +```yaml +volumeSnapshots: + enabled: true + driver: ebs.csi.aws.com + class: okteto-snapshot-class + storageClass: okteto-snapshot-sc +``` + + + + +```yaml +volumeSnapshots: + enabled: true + driver: pd.csi.storage.gke.io + class: okteto-snapshot-class + storageClass: okteto-snapshot-sc +``` + + + + +```yaml +volumeSnapshots: + enabled: true + driver: dobs.csi.digitalocean.com + class: okteto-snapshot-class + storageClass: okteto-snapshot-sc +``` + + + + +By default, all users in your cluster will be able to use any of the available snapshots as a data source for their development environments. You can limit this via the `enableNamespaceAccessValidation` key in the `volumeSnapshots` section of the configuration, value of `true` will enable the validation. + +## Using Volume Snapshots in your Development Environment + +Follow [this guide](cloud/volume-snapshots.mdx/#using-volume-snapshots-in-your-development-environment) to use Volume Snapshots in your development environment. diff --git a/versioned_docs/version-1.5/self-hosted/aks.mdx b/versioned_docs/version-1.5/self-hosted/aks.mdx new file mode 100644 index 000000000..1d75eba73 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/aks.mdx @@ -0,0 +1,232 @@ +--- +title: Azure Kubernetes Service (AKS) +description: How to install Okteto onto Azure Kubernetes Service (AKS) +id: aks +--- + +This guide will show you how to install Okteto onto Azure Kubernetes Service (AKS). We'll be focusing exclusively on AKS in order to keep it as simple as possible. + +## Requirements + +In order to fully install Okteto, you'll need the following: + +- A subdomain to which you can add a wildcard DNS record +- A Kubernetes cluster +- A working installation of kubectl +- A working installation of Helm v3 +- An OAuth application +- An Azure Storage Container +- An Okteto license (optional) + +### Subdomain + +You'll need access to a subdomain to which you can add a wildcard DNS record, such as dev.example.com. + +This guide will assume that your domain is registered in [AzureDNS](https://docs.microsoft.com/en-us/azure/dns/dns-overview). Other DNS services can be used, but aren't covered here. + +### Deploy a Kubernetes cluster + +We recommend that you follow Azure's [cluster creation guide](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough). +Okteto supports Kubernetes versions 1.21 through 1.23. + +We recommend the following specs: +- v1.23 +- A pool with at least 3 `Standard D4` nodes +- 250 GB per Standard SSD Managed Disk + +You'll be using the cluster's API server endpoint when configuring Okteto. +Run the following command to obtain your cluster's API server endpoint: + +``` +kubectl config view --minify | grep server +``` + +> Our installation guides assume Okteto will be running in a dedicated cluster. We recommend [contacting our team](https://www.okteto.com/contact/) if you plan on installing Okteto in a cluster with other workloads. + +### Installing kubectl + +Follow Azure's documentation for [installing kubectl](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough#connect-to-the-clusterl). Once installed, configure `kubectl` to talk to your new cluster. + +### Installing Helm v3 + +Follow the official documentation for [installing the latest release of Helm v3](https://helm.sh/docs/intro/install/). + +### Creating the OAuth application + +> Okteto supports OAuth providers like Google, GitHub, or OpenID Connect to handle user authentication. For this guide, we'll focus on using GitHub. All the supported configuration settings [are described here](self-hosted/administration/configuration.mdx#auth). + + +> If you are planning on using the GitHub Integration, you should follow [this guide](self-hosted/administration/configuration.mdx#creating-the-github-app). 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](https://developer.github.com/apps/building-oauth-apps/creating-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 +``` + +You'll use the `Client ID` and `Client Secret` when installing Okteto. + +### Creating an Azure Storage Container + +Okteto uses a storage container to store your private images. Follow Azure's [guide on how to create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction). Create the bucket in the region as your AKS cluster, and keep it private. + +You'll need the Account Name and a Storage Account Key when installing Okteto. + +## Adding the Okteto Helm repository + +You'll need to add the Okteto repository in order to be able to install Okteto: + +```console +helm repo add okteto https://charts.okteto.com +helm repo update +``` + +### Getting your Okteto License + +Okteto is free for up to 3 users without a license. +You can also sign on for the [free trial](https://www.okteto.com/free-trial/) to give access up to 100 users for a month. + +## Installing Okteto + +### Create the Okteto Namespace + +Run the following command to create a namespace to install Okteto in: + +```console +$ kubectl create namespace okteto +``` + +### Configuring your Okteto instance + +Create a Kubernetes secret with the Storage Account Access Key you created before: + +```console +kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=STORAGE_ACCOUNT_ACCESS_KEY +``` + +Download a copy of the [Okteto AKS configuration file](https://www.okteto.com/docs/self-hosted/aks/config.yaml), open it, and update the following values: + +- Your `email` +- Your `license` (optional) +- A `subdomain` +- `clientId` and `clientSecret` of the OAuth Application you created +- You GitHub `organization`. An empty `organization` field permits any user to log in. +- Your cluster's API server endpoint +- The name of the `storage container` you created +- The `Storage Account Name` + +For example: + +```yaml +email: admin@example.com +license: 1234567890ABCD== +subdomain: dev.example.com +cluster: + endpoint: "https://XXXXXX.aks.microsoft.com" + +auth: + github: + enabled: true + clientId: ae8924d074d8c8809999 + clientSecret: ABCD90598b706d5342f07cce18fee5e5da391234 + organization: my-org + +cloud: + provider: + azure: + enabled: true + storage: + container: "okteto-container" + accountName: "okteto-storage-account" + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer +``` + +### Installing your Okteto instance + +Install the latest version of Okteto by running: + +```console +helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +After a few seconds, all the resources will be created. The output will look something like this: + +``` +Release "okteto" has been installed. Happy Helming! +NAME: okteto +LAST DEPLOYED: Thu Mar 26 18:07:55 2020 +NAMESPACE: okteto +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +1. Create the following DNS record, pointing it to the NGINX controller service External-IP: +- "*.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto + +2. Create the following DNS record, pointing it to the Buildkit service External-IP: +- "buildkit.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto + +3. Once you create both DNS entries you can access your Okteto instance at this URL: +https://okteto.dev.example.com +``` + +> You can also install a specific version by including the `--version` argument. + +### Retrieve the Ingress Controller IP address + +We can use the instructions `kubectl` to fetch the address that has been dynamically allocated by AKS to the NGINX Ingress we've just installed and configured as a part of Okteto: + +```console +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 a519c8b3b27f94...aks.microsoft.com 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address and add it to your DNS for the domain you have chosen to use. In AzureDNS, this is done by creating an `A` record with the name `*`, pointing to the IP of the Load Balancer. + +### Retrieve the Buildkit IP address + +You can use `kubectl` to fetch the address that has been dynamically allocated by AKS to the Buildkit instance you've just installed and configured as a part of Okteto: + +```console +kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto +``` + +The output will look something like this: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-buildkit LoadBalancer 10.245.142.73 a519c8b3b27f95...aks.microsoft.com 1234:32449/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. This is done by creating an `A` record with the name `buildkit`. + +## Sign in to your Okteto instance + +> **Important**: The default installation uses self-signed certificates. We strongly recommend that you configure Okteto to [bring your own certificates](self-hosted/administration/certificates.mdx) before giving your team access to your instance. + +You can access your Okteto instance at `https://okteto.SUBDOMAIN`. Your account will be automatically created as part of the login process. The first user to successfully log into the instance will be automatically assigned the `administrator` role. diff --git a/versioned_docs/version-1.5/self-hosted/aks/config.yaml b/versioned_docs/version-1.5/self-hosted/aks/config.yaml new file mode 100644 index 000000000..cd342585a --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/aks/config.yaml @@ -0,0 +1,29 @@ +email: + +license: + +subdomain: + +auth: + github: + enabled: true + clientId: + clientSecret: + organization: + +cluster: + endpoint: + +cloud: + provider: + azure: + enabled: true + storage: + container: "" + accountName: "" + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer \ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/civo.mdx b/versioned_docs/version-1.5/self-hosted/civo.mdx new file mode 100644 index 000000000..bde4dee38 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/civo.mdx @@ -0,0 +1,197 @@ +--- +title: Civo +description: How to install Okteto onto Civo +id: civo +--- + +import Image from '@theme/Image'; + +This guide will show you how to install Okteto onto Civo's Kubernetes Service. + +## Requirements + +In order to fully install Okteto, you'll need the following: + +- A subdomain to which you can add a wildcard DNS record +- A Kubernetes cluster +- A working installation of kubectl +- A working installation of Helm v3 +- A GitHub OAuth application +- An Okteto License (optional) + +### Subdomain + +You'll need access to a subdomain to which you can add a wildcard DNS record, such as dev.example.com. + +This guide will assume that your domain is registered in [Civo](https://www.civo.com/account/dns). Other DNS services can be used, but aren't covered here. + +In the rest of this guide, we will refer to this subdomain as `DOMAIN`. + +### Deploy a Kubernetes cluster + +If you are not familiar with this step, we recommend that you follow Civos's [cluster creation guide](https://www.civo.com/learn/kubernetes-cluster-administration-using-civo-cli). + +To get started with Okteto, we recommend that you create a Kubernetes cluster with the following configuration: + +- 3 large nodes +- Default network +- Without Traefik (you'll need to remove it from the default apps) + +Okteto will create persistent volumes for the build and registry services, so you might need to increase [your storage quotas](https://www.civo.com/account/quota). + +> Our installation guides assume Okteto will be running in a dedicated cluster. We recommend [contacting our team](https://www.okteto.com/contact/) if you plan on installing Okteto in a cluster with other workloads. + +### Installing kubectl + +Follow the official documentation for [installing kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). Once installed, configure `kubectl` to [talk to your new cluster](https://www.civo.com/learn/kubernetes-cluster-administration-using-civo-cli#downloading-the-cluster-39-s-configuration). + +### Installing Helm v3 + +Follow the official documentation for [installing the latest release of Helm v3](https://helm.sh/docs/intro/install/). + +### Creating the GitHub OAuth application + +> Okteto supports OAuth providers like Google, GitHub, or OpenID Connect to handle user authentication. For this guide, we'll focus on using GitHub. All the supported configuration settings [are described here](self-hosted/administration/configuration.mdx#auth). + +> If you are planning on using the GitHub Integration, you should follow [this guide](self-hosted/administration/configuration.mdx#creating-the-github-app). 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](https://developer.github.com/apps/building-oauth-apps/creating-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 +``` + +You'll use the `Client ID` and `Client Secret` when installing Okteto. + +### Getting your Okteto License + +Okteto is free for up to 3 users without a license. +You can also sign on for the [free trial](https://www.okteto.com/free-trial/) to give access up to 100 users for a month. + +## Installing Okteto + +### Create the Okteto Namespace + +Run the following command to create a namespace to install Okteto in: + +```console +$ kubectl create namespace okteto +``` + +### Configuring your Okteto instance + +Download a copy of the [Okteto Civo configuration file](https://www.okteto.com/docs/self-hosted/civo/config.yaml), open it, and update the following values: + +- Your `email` +- Your `license` (optional) +- A `subdomain` +- `clientId` and `clientSecret` of the GitHub OAuth Application you created +- You GitHub `organization`. An empty `organization` field permits any user to log in. + +For example: + +```yaml +email: admin@example.com +license: 1234567890ABCD== +subdomain: dev.example.com +auth: + github: + enabled: true + clientId: ae8924d074d8c8809999 + clientSecret: ABCD90598b706d5342f07cce18fee5e5da391234 + organization: my-org + +cloud: + provider: + civo: + enabled: true + +registry: + storage: + filesystem: + enabled: true + persistence: + size: 100Gi +``` + +### Adding the Okteto Helm repository + +You'll need to add the Okteto repository in order to be able to install Okteto: + +```console +helm repo add okteto https://charts.okteto.com +helm repo update +``` + +### Installing your Okteto instance + +Install the latest version of Okteto by running: + +```console +helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +After a few seconds, all the resources will be created. The output will look something like this: + +``` +Release "okteto" has been installed. Happy Helming! +NAME: okteto +LAST DEPLOYED: Thu Mar 26 18:07:55 2020 +NAMESPACE: okteto +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +1. Create the following DNS record, pointing it to the NGINX controller service External-IP: +- "*.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto + +2. Once you create both DNS entries you can access your Okteto instance at this URL: +https://okteto.dev.example.com +``` + +### Retrieve the Ingress Controller IP address + +You can use `kubectl` to fetch the address that has been dynamically allocated by Civo to the NGINX Ingress you've just installed and configured as a part of Okteto: + +```console +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.245.147.23 91.211.154.196 80:30087/TCP,443:31799/TCP,1234:31412/TC 2m +``` + +You'll need to create a wildcard DNS record for this IP. To do that, log in to your Civo account, click on the "Manage" option on the left part of the dashboard, and click on "DNS". + +Select the domain you're using for your Okteto instance, and click on the "DNS Records" option. + +

Screenshot of the CIVO app and the DNS Records settings

+ +Click on the "Add a Record" button and use the following values: +- Type: A +- Name: * +- Value: Your EXTERNAL-IP + +

Screenshot of the CIVO app and the New Domain Record component

+ +Click on the "Add Record" button to create the DNS record. + +## Sign in to your Okteto instance + +> **Important**: The default installation uses self-signed certificates. We strongly recommend that you configure Okteto to [bring your own certificates](self-hosted/administration/certificates.mdx) before giving your team access to your instance. + +You can access your Okteto instance at `https://okteto.SUBDOMAIN`. Your account will be automatically created as part of the login process. The first user to successfully log into the instance will be automatically assigned the `administrator` role. diff --git a/versioned_docs/version-1.5/self-hosted/civo/config.yaml b/versioned_docs/version-1.5/self-hosted/civo/config.yaml new file mode 100644 index 000000000..2de534c6d --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/civo/config.yaml @@ -0,0 +1,24 @@ +email: + +license: + +subdomain: + +auth: + github: + enabled: true + clientId: + clientSecret: + organization: + +cloud: + provider: + civo: + enabled: true + +registry: + storage: + filesystem: + enabled: true + persistence: + size: 100Gi \ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/digitalocean.mdx b/versioned_docs/version-1.5/self-hosted/digitalocean.mdx new file mode 100644 index 000000000..517624c2e --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/digitalocean.mdx @@ -0,0 +1,239 @@ +--- +title: DigitalOcean Kubernetes (DOKS) +description: How to install Okteto onto DigitalOcean Kubernetes +id: do +--- + +This guide will show you how to install Okteto onto DigitalOcean Kubernetes. We'll be focusing exclusively on DigitalOcean Kubernetes in order to keep it as simple as possible. + +## Requirements + +In order to fully install Okteto, you'll need the following: + +- A subdomain to which you can add a wildcard DNS record +- A Kubernetes cluster +- A working installation of kubectl +- A working installation of Helm v3 +- A GitLab OAuth application +- A DigitalOcean personal access token +- A DigitalOcean space and access key +- An Okteto License (optional) + +### Subdomain + +You'll need access to a subdomain to which you can add a wildcard DNS record, such as dev.example.com. + +This guide will assume that your domain is registered in [DigitalOcean](https://cloud.digitalocean.com/networking/domains). Other DNS services can be used, but aren't covered here. + +In the rest of this guide, we will refer to this subdomain as `DOMAIN`. + +### Deploy a Kubernetes cluster + +If you are not familiar with this step, we recommend that you follow DigitalOcean's [cluster creation guide](https://www.digitalocean.com/docs/kubernetes/how-to/create-clusters/). +Okteto supports Kubernetes versions 1.21 through 1.23. + +To get started with Okteto, follow these specs: + +- v1.23 +- A pool with at least 2 nodes (4CPUs and 16GBs each) without autoscalability +- 250 GB per disk + +You'll be using the cluster's API server endpoint when configuring Okteto. +Run the following command to obtain your cluster's API server endpoint: + +``` +kubectl config view --minify | grep server +``` + +> Our installation guides assume Okteto will be running in a dedicated cluster. We recommend [contacting our team](https://www.okteto.com/contact/) if you plan on installing Okteto in a cluster with other workloads. + +### Installing kubectl + +Follow the official documentation for [installing kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). Once installed, configure `kubectl` to [talk to your new cluster](https://www.digitalocean.com/docs/kubernetes/how-to/connect-to-cluster/). + +### Installing Helm v3 + +Follow the official documentation for [installing the latest release of Helm v3](https://helm.sh/docs/intro/install/). + +### Creating the GitLab OAuth application + +Okteto supports OAuth providers like Google, Bitbucket, GitHub, or OpenID Connect to handle user authentication. All the supported configuration settings [are described here](self-hosted/administration/configuration.mdx#auth). + +For this guide, we will focus on using GitLab OpenID Connect. + +Follow GitLab's official documentation on [how to create an OAuth Client](https://docs.gitlab.com/ee/integration/oauth_provider.html). + +When creating the OAuth Application, you will need to provide the following values: + +**Redirect URIs**: +``` +https://okteto.DOMAIN +https://okteto.DOMAIN/auth/callback +``` + +**Scopes**: +``` +openid +profile +email +``` + +You'll use the `Application ID` and `Secret` of your OAuth Application when installing Okteto. + +### Creating a DigitalOcean Space and Access Key + +Okteto uses DigitalOcean spaces to store your private images. Follow DigitalOcean's [guide on how to create a space and api key](https://www.digitalocean.com/community/tutorials/how-to-create-a-digitalocean-space-and-api-key). +Create the space in the same region as your Kubernetes cluster and restrict file listing. + +### Getting your Okteto License + +Okteto is free for up to 3 users without a license. +You can also sign on for the [free trial](https://www.okteto.com/free-trial/) to give access up to 100 users for a month. + +## Installing Okteto + +### Create the Okteto Namespace + +Run the following command to create a namespace to install Okteto in: + +```console +$ kubectl create namespace okteto +``` + +### Configuring your Okteto instance + +Create a Kubernetes secret with the DigitalOcean space access key secret (`$SECRET`) you created before: + +```console +$ kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=$SECRET +``` + +Using these values: + +- Your email: `$EMAIL` +- Your license (optional): `$LICENSE` +- Your subdomain: `$SUBDOMAIN` +- Your cluster's API server endpoint +- The URL of your GitLab instance: `$GITLAB_URL`. Use https://gitlab.com if your are using GitLab SaaS +- Application ID: `$OAUTH_APPLICATION_ID` and Secret: `$OAUTH_APPLICATION_SECRET` of the OAuth 2.0 Client you created +- The ID of the DigitalOcean region of your Kubernetes cluster: `$REGION` +- Your space name: `$SPACE_NAME` and access key ID : `$SPACE_ACCESS_KEY_ID` + +create the following `config.yml` file to configure the Okteto Helm chart: + +```yaml +email: "$EMAIL" +license: "$LICENSE" +subdomain: "$SUBDOMAIN" + +cluster: + endpoint: "$KUBERNETES_ENDPOINT" + +auth: + openid: + enabled: true + endpoints: + issuer: "$GITLAB_URL" + authorization: "$GITLAB_URL/oauth/authorize" + clientId: "$OAUTH_APPLICATION_ID" + clientSecret: "$OAUTH_APPLICATION_SECRET" + +cloud: + provider: + digitalocean: + enabled: true + region: "$REGION" + space: + name: "$SPACE_NAME" + accessKeyID: "$SPACE_ACCESS_KEY_ID" + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer +``` + +### Adding the Okteto Helm repository + +You'll need to add the Okteto repository in order to be able to install Okteto: + +```console +helm repo add okteto https://charts.okteto.com +helm repo update +``` + +### Installing your Okteto instance + +Install the latest version of Okteto by running: + +```console +helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +After a few seconds, all the resources will be created. The output will look something like this: + +``` +Release "okteto" has been installed. Happy Helming! +NAME: okteto +LAST DEPLOYED: Thu Mar 26 18:07:55 2020 +NAMESPACE: okteto +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +1. Create the following DNS record, pointing it to the NGINX controller service External-IP: +- "*.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto + +2. Create the following DNS record, pointing it to the Buildkit service External-IP: +- "buildkit.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto + +3. Once you create both DNS entries you can access your Okteto instance at this URL: +https://okteto.dev.example.com +``` + +### Retrieve the Ingress Controller IP address + +You can use `kubectl` to fetch the address that has been dynamically allocated by DigitalOcean to the NGINX Ingress you've just installed and configured as a part of Okteto: + +```console +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.245.147.23 64.225.83.163 80:30087/TCP,443:31799/TCP,1234:31412/TC 2m +``` + +You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. This is done by creating an `A` record with the name `*`. + +### Retrieve the Buildkit IP address + +You can use `kubectl` to fetch the address that has been dynamically allocated by DigitalOcean to the Buildkit instance you've just installed and configured as a part of Okteto: + +```console +kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto +``` + +The output will look something like this: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-buildkit LoadBalancer 10.245.142.73 64.225.83.88 1234:32449/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. This is done by creating an `A` record with the name `buildkit`. + +## Sign in to your Okteto instance + +> **Important**: The default installation uses self-signed certificates. We strongly recommend that you configure Okteto to [bring your own certificates](self-hosted/administration/certificates.mdx) before giving your team access to your instance. + +You can access your Okteto instance at `https://okteto.SUBDOMAIN`. Your account will be automatically created as part of the login process. The first user to successfully log into the instance will be automatically assigned the `administrator` role. diff --git a/versioned_docs/version-1.5/self-hosted/digitalocean/config.png b/versioned_docs/version-1.5/self-hosted/digitalocean/config.png new file mode 100644 index 000000000..fdc148da2 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/digitalocean/config.png differ diff --git a/versioned_docs/version-1.5/self-hosted/digitalocean/config.yaml b/versioned_docs/version-1.5/self-hosted/digitalocean/config.yaml new file mode 100644 index 000000000..79d9a5446 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/digitalocean/config.yaml @@ -0,0 +1,33 @@ +email: + +license: + +subdomain: + +auth: + openid: + enabled: true + endpoints: + issuer: + authorization: + clientId: + clientSecret: + +cluster: + endpoint: + +registry: + storage: + filesystem: + enabled: true + +cloud: + provider: + digitalocean: + enabled: true + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer \ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/digitalocean/dns.png b/versioned_docs/version-1.5/self-hosted/digitalocean/dns.png new file mode 100644 index 000000000..ba3391fd9 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/digitalocean/dns.png differ diff --git a/versioned_docs/version-1.5/self-hosted/digitalocean/marketplace.md b/versioned_docs/version-1.5/self-hosted/digitalocean/marketplace.md new file mode 100644 index 000000000..001e6d5e1 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/digitalocean/marketplace.md @@ -0,0 +1,96 @@ +--- +title: Getting started after deploying Okteto +--- + +import Image from '@theme/Image'; + +After you have downloaded your `kubeconfig` file and can successfully connect to your DigitalOcean Kubernetes cluster (see https://cloud.digitalocean.com/kubernetes/clusters/ if you haven't connected to your cluster), follow the instructions below to start using Okteto. + +## Initial Configuration + +The first step is to get your admin token. Run the following command in a terminal shell to retrieve it: + +```console +kubectl get sa -n=okteto do-okteto -ojsonpath='{.metadata.labels.dev\.okteto\.com/token}' +``` + +Second, start a port-forward to the ingress service by running the command below: + +```console +kubectl port-forward service/do-ingress-nginx-controller 8443:443 --namespace okteto +``` + +Third, open your browser and go to [https://localhost:8443/#admin](https://localhost:8443/#admin) to load the admin screen. + +Use the admin token you retrieved on the first step to log in to the admin screen. + +Once you log in to the admin page, you'll need to provide the following values to complete Okteto's initial configuration. + +1. The email of the owner of the application +1. A [dedicated subdomain](#Subdomain) for your Okteto instance +1. Your Kubernetes cluster's [public endpoint](#Cluster-Public-Endpoint) +1. Your [Okteto license](#License) (optional) +1. The Client ID and Client Secret of a [GitHub OAuth app](#Authentication) +1. A list of the GitHub Usernames allowed to log into your Okteto instance (optional, leave it empty to allow everyone) +1. A DigitalOcean [personal access token](#Personal-Access-Token) + +Press `Save` once you're ready to apply the new configuration. It'll take about 30 seconds for the configuration to be applied. + +Your Okteto instance is now fully configured. It will be available via https://okteto.$SUBDOMAIN (e.g. https://okteto.dev.example.com). The [next section ](#DNS-configuration) explains how to configure the DNS for this. + +## DNS configuration + +Run the following command in a terminal shell to get the External IP address of the Load Balancer. + +```console +kubectl get svc -n=okteto -l="app=nginx-ingress,component=controller" +``` + +Create a [wildcard A record](https://cloud.digitalocean.com/networking/domains) for the entire subdomain and point it to the load balancer's external IP. + +![DNS configuration](https://www.okteto.com/docs/self-hosted/digitalocean/dns.png) + +## More information + +### Subdomain + +Okteto can automatically create HTTPS endpoints for the applications you deploy in your cluster. We recommend that you give Okteto a dedicated subdomain to prevent endpoint clashes with other applications. + +The Okteto web UI will always be available at https://okteto.$SUBDOMAIN. + +The subdomain must be [registered with Digital Ocean](https://www.digitalocean.com/docs/networking/dns/how-to/add-domains/). + +### Cluster Public Endpoint + +This is the fully qualified URL of your Kubernetes cluster's apiserver. You can get it from the `kubeconfig` file you downloaded from DigitalOcean: + +``` +apiVersion: v1 +clusters: +- cluster: + certificate-authority-data: DATA+OMITTED + server: https://0b84ec60-fe41-4994-8e76-b53e00859ef9.k8s.ondigitalocean.com + name: do-sfo2-ramiro + ... +``` + +### License +Okteto is free for small teams. You get all the features of [Okteto](https://okteto.com/docs/self-hosted/) for up to 3 users. Need more? [Let's talk](https://okteto.com/#talktous). + +### Authentication + +Okteto uses GitHub OAuth as the authentication provider. You'll need to create a [GitHub OAuth app](https://developer.github.com/apps/building-oauth-apps/creating-an-oauth-app/) with the following values: + +*Homepage URL:* +https://okteto.$SUBDOMAIN + +*Authorization callback URL:* +https://okteto.$SUBDOMAIN/auth/callback + +### Personal Access Token + +Okteto requires a DigitalOcean personal access token with read/write permissions to create DNS entries when responding to [ACME DNS-01 challenges](https://letsencrypt.org/docs/challenge-types/#dns-01-challenge). The entries will be created in the subdomain you provided in the configuration. Create your [personal access token here](https://cloud.digitalocean.com/account/api/tokens). + +## Support + +If you get stuck or have any questions, feel free to reach out to us at hello@okteto.com, [Twitter](https://twitter.com/oktetohq), or [our community](https://community.okteto.com/). diff --git a/versioned_docs/version-1.5/self-hosted/eks.mdx b/versioned_docs/version-1.5/self-hosted/eks.mdx new file mode 100644 index 000000000..79e6247e2 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/eks.mdx @@ -0,0 +1,275 @@ +--- +title: Amazon Elastic Kubernetes Service (EKS) +description: How to install Okteto onto Amazon Elastic Kubernetes Service (EKS) +id: eks +--- + +This guide will show you how to install Okteto onto Amazon Elastic Kubernetes Service (EKS). We'll be focusing exclusively on EKS in order to keep it as simple as possible. + +## Requirements + +In order to fully install Okteto, you'll need the following: + +- A subdomain to which you can add a wildcard DNS record +- A Kubernetes cluster +- A working installation of kubectl +- A working installation of Helm v3 +- A GitHub OAuth application +- An IAM user +- An S3 bucket +- An Okteto License (optional) + +### Subdomain + +You'll need access to a subdomain to which you can add a wildcard DNS record, such as dev.example.com. + +This guide will assume that your domain is registered in [Amazon Route53](https://aws.amazon.com/route53/). Other DNS services can be used, but aren't covered here. + +### Deploy a Kubernetes cluster + +We recommend that you follow Amazon's [cluster creation guide](https://docs.aws.amazon.com/eks/latest/userguide/create-cluster.html). +Okteto supports Kubernetes versions 1.21 through 1.23. + +We recommend the following specs: +- v1.23 +- A pool with at least 3 `m4.xlarge` nodes +- 250 GB per disk + +You'll be using the cluster's API server endpoint when configuring Okteto. +Run the following command to obtain your cluster's API server endpoint: + +``` +kubectl config view --minify | grep server +``` + +> Our installation guides assume Okteto will be running in a dedicated cluster. We recommend [contacting our team](https://www.okteto.com/contact/) if you plan on installing Okteto in a cluster with other workloads. + +### Installing kubectl + +Follow Amazon's documentation for [installing kubectl](https://docs.aws.amazon.com/eks/latest/userguide/install-kubectl.html). Once installed, configure `kubectl` to [talk to your new cluster](https://docs.aws.amazon.com/eks/latest/userguide/create-kubeconfig.html). + +### Installing Helm v3 + +Follow the official documentation for [installing the latest release of Helm v3](https://helm.sh/docs/intro/install/). + +### Creating the GitHub OAuth application + +> Okteto supports OAuth providers like Google, GitHub, or OpenID Connect to handle user authentication. For this guide, we'll focus on using GitHub. All the supported configuration settings [are described here](self-hosted/administration/configuration.mdx#auth). + +> If you are planning on using the GitHub Integration, you should follow [this guide](self-hosted/administration/configuration.mdx#creating-the-github-app). 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](https://developer.github.com/apps/building-oauth-apps/creating-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 +``` + +You'll use the `Client ID` and `Client Secret` when installing Okteto. + +### Creating an Amazon S3 Bucket + +Okteto uses S3 to store your private images. Follow Amazon's [guide on how to create s3 buckets](https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html). Create the bucket in the region as your EKS cluster, and keep it private. + +### Creating an IAM + +The Okteto Registry needs access to a S3 bucket to store your container images. + +We recommend you follow AWS' official documentation on [how to create and manage IAM Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) for more information on this. + +You'll need to perform the following tasks: + +1. Create an `IAM User` +1. Create a set of Access keys for your `IAM User` and save them locally. We'll be using this when installing Okteto +1. Create an `IAM Policy` with the following permissions (replace `YOUR_BUCKET` with your `s3` bucket name) + ```json + { + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation", + "s3:ListBucketMultipartUploads" + ], + "Resource": "arn:aws:s3:::YOUR_BUCKET" + }, + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:ListMultipartUploadParts", + "s3:AbortMultipartUpload" + ], + "Resource": "arn:aws:s3:::YOUR_BUCKET/*" + } + ] + } + ``` +1. Attach the previous `IAM Policy` to the previous `IAM User` + +## Adding the Okteto Helm repository + +You'll need to add the Okteto repository to be able to install Okteto: + +```console +helm repo add okteto https://charts.okteto.com +helm repo update +``` + +### Getting your Okteto License + +Okteto is free for up to 3 users without a license. +You can also sign on for the [free trial](https://www.okteto.com/free-trial/) to give access up to 100 users for a month. + +## Installing Okteto + +### Create the Okteto Namespace + +Run the following command to create a namespace to install Okteto in: + +```console +$ kubectl create namespace okteto +``` + +### Configuring your Okteto instance + +Create a Kubernetes secret with the IAM User's Access secret key you created before: + +```console +kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=IAM_ACCESS_SECRET +``` + +Download a copy of the [Okteto EKS configuration file](https://www.okteto.com/docs/self-hosted/eks/config.yaml), open it, and update the following values: + +- Your `email` +- Your `license` (optional) +- A `subdomain` +- `clientId` and `clientSecret` of the OAuth Application you created +- You GitHub `organization`. An empty `organization` field permits any user to log in. +- Your cluster's API server endpoint +- The name of the `bucket` you created +- The `Access key ID` of the IAM User + +> You can also configure Okteto to assume a role instead of using access keys. Check the [AWS section in the configuration page](self-hosted/administration/configuration.mdx#cloud) to learn more. + +For example: + +```yaml +email: admin@example.com +license: 1234567890ABCD== +subdomain: dev.example.com +cluster: + endpoint: "https://XXXXXX.gr7.us-west-2.eks.amazonaws.com" + +auth: + github: + enabled: true + clientId: ae8924d074d8c8809999 + clientSecret: ABCD90598b706d5342f07cce18fee5e5da391234 + organization: my-org + +cloud: + provider: + aws: + enabled: true + region: us-west-2 + bucket: okteto-private-images + iam: + accessKeyID: "XXXXXX" + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer +``` + +### Installing your Okteto instance + +Install the latest version of Okteto by running: + +```console +helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +After a few seconds, all the resources will be created. The output will look something like this: + +``` +Release "okteto" has been installed. Happy Helming! +NAME: okteto +LAST DEPLOYED: Thu Mar 26 18:07:55 2020 +NAMESPACE: okteto +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +1. Create the following DNS record, pointing it to the NGINX controller service External-IP: +- "*.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto + +2. Create the following DNS record, pointing it to the Buildkit service External-IP: +- "buildkit.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto + +3. Once you create both DNS entries you can access your Okteto instance at this URL: +https://okteto.dev.example.com +``` + +> You can also install a specific version by including the `--version` argument. + +### Retrieve the Ingress Controller IP address + +We can use the instructions `kubectl` to fetch the address that has been dynamically allocated by EKS to the NGINX Ingress we've just installed and configured as a part of Okteto: + +```console +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 a519c8b3b27f94...elb.amazonaws.com 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. In Route 53, this is done by creating an `A` record with the name `*`, pointing to the alias of the Elastic Load Balancer. + +> Note: avoid using a `CNAME` record for `*` pointing to the public hostname of the Elastic Load Balancer, as it will block the cert-manager default capability for issuing/renewing certificates via ACME dns01. + +### Retrieve the Buildkit IP address + +You can use `kubectl` to fetch the address that has been dynamically allocated by EKS to the Buildkit instance you've just installed and configured as a part of Okteto: + +```console +kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto +``` + +The output will look something like this: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-buildkit LoadBalancer 10.245.142.73 a519c8b3b27f95...elb.amazonaws.com 1234:32449/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address and add it to your DNS for the domain you have chosen to use. This is done by creating an `A` record with the name `buildkit`. + +## Sign in to your Okteto instance + +> **Important**: The default installation uses self-signed certificates. We strongly recommend that you configure Okteto to [bring your own certificates](self-hosted/administration/certificates.mdx) before giving your team access to your instance. + +You can access your Okteto instance at `https://okteto.SUBDOMAIN`. Your account will be automatically created as part of the login process. The first user to successfully log into the instance will be automatically assigned the `administrator` role. diff --git a/versioned_docs/version-1.5/self-hosted/eks/config.yaml b/versioned_docs/version-1.5/self-hosted/eks/config.yaml new file mode 100644 index 000000000..8a38e1ba2 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/eks/config.yaml @@ -0,0 +1,31 @@ +email: + +license: + +subdomain: + +auth: + github: + enabled: true + clientId: + clientSecret: + organization: + +cluster: + endpoint: + +cloud: + provider: + aws: + enabled: true + region: + bucket: + iam: + enabled: true + accessKeyID: + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer \ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/gke.mdx b/versioned_docs/version-1.5/self-hosted/gke.mdx new file mode 100644 index 000000000..cf2343c92 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/gke.mdx @@ -0,0 +1,240 @@ +--- +title: Google Kubernetes Engine (GKE) +description: How to install Okteto onto Google Kubernetes Engine (GKE) +id: gke +--- + +This guide will show you how to install Okteto onto Google Kubernetes Engine (GKE). We'll be focusing exclusively on GKE in order to keep it as simple as possible. + +## Requirements + +In order to fully install Okteto, you will need the following: + +- A subdomain to which you can add a wildcard DNS record +- A Kubernetes cluster +- A working installation of kubectl +- A working installation of Helm v3 +- A Google (or GitHub) OAuth application +- A Google Cloud service account and a key +- A Google Cloud Storage bucket +- An Okteto License (optional) + +### Subdomain + +You'll need access to a subdomain to which you can add a wildcard DNS record, such as dev.example.com. + +This guide will assume that your domain is registered in Google's [Cloud DNS](https://cloud.google.com/dns). Other DNS services can be used as well, but are not covered by this guide. + +### Deploy a Kubernetes cluster + +We recommend that you follow Google's [GKE cluster creation guide](https://cloud.google.com/kubernetes-engine/docs/how-to/creating-a-cluster). +Okteto supports Kubernetes versions 1.21 through 1.23. + +We recommend the following specs: +- v1.23 +- A pool with at least 3 `n1-standard-4` nodes +- 250 GB per disk + +You'll be using the cluster's API server endpoint when configuring Okteto. +Run the following command to obtain your cluster's API server endpoint: + +``` +kubectl config view --minify | grep server +``` + +> Our installation guides assume Okteto will be running in a dedicated cluster. We recommend [contacting our team](https://www.okteto.com/contact/) if you plan on installing Okteto in a cluster with other workloads. + +### Installing kubectl + +Follow the official documentation for [installing kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). Once installed, configure `kubectl` to [talk to your new cluster](https://cloud.google.com/kubernetes-engine/docs/how-to/cluster-access-for-kubectl#generate_kubeconfig_entry). + + +### Installing Helm v3 + +Follow the official documentation for [installing the latest release of Helm v3](https://helm.sh/docs/intro/install/). + +### Creating the Google OAuth application + +> Okteto supports OAuth providers like Google, GitHub, or OpenID Connect to handle user authentication. For this guide, we will focus on using Google. All the supported configuration settings [are described here](self-hosted/administration/configuration.mdx#auth). + +Follow Google's official documentation on [how to create an OAuth 2.0 Client](https://support.google.com/cloud/answer/6158849?hl=en). + +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 +``` + +You'll use the `client ID` and `client Secret` when installing Okteto. + +### Creating a Google Cloud Storage Bucket + +Okteto uses Google Cloud Storage to store your private images. Follow Google's [guide on how to create storage buckets](https://cloud.google.com/storage/docs/quickstart-console). Create the bucket in the same project and region as your GKE cluster, and keep it private. + +### Creating a Google Cloud Service Account + +The Okteto Registry needs access to Cloud Storage for uploading and downloading your container images. + +We recommend you follow Google's official documentation on [how to create and manage Service Accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts) for more information on this. + +You'll need to perform the following tasks: + +1. Create a `Service Account` in the same Google Cloud project as your GKE cluster. +1. Give it the `Storage Object Admin` roles. +1. Create a `JSON` key and save it locally. We'll be using this when installing Okteto. + +## Adding the Okteto Helm repository + +You'll need to add the Okteto repository in order to be able to install Okteto: + +```console +helm repo add okteto https://charts.okteto.com +helm repo update +``` + +### Getting your Okteto License + +Okteto is free for up to 3 users without a license. +You can also sign on for the [free trial](https://www.okteto.com/free-trial/) to give access up to 100 users for a month. + +## Installing Okteto + +### Create the Okteto Namespace + +Run the following command to create a namespace to install Okteto in: + +```console +$ kubectl create namespace okteto +``` + +### Configuring your Okteto instance + +Create a Kubernetes secret with the `Service Account` key you created before: + +```console +kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-file=key=$PATH_TO_KEY_FILE +``` + +Download a copy of the [Okteto GKE configuration file](https://www.okteto.com/docs/self-hosted/gke/config.yaml), open it, and set the following values: + +- Your `email` +- Your `license` (optional) +- A `subdomain` +- `clientId` and `clientSecret` of the OAuth 2.0 Client you created +- Your cluster's API server endpoint +- The name of the `bucket` you created +- The `project` id of your cluster + +For example: + +```yaml +email: admin@example.com +license: 1234567890ABCD== +subdomain: dev.example.com + +auth: + google: + enabled: true + clientId: clientid.apps.googleusercontent.com + clientSecret: clientSecret + +cluster: + endpoint: https://35.205.100.149 + +cloud: + provider: + gcp: + enabled: true + project: okteto-dev + bucket: okteto-private-images + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer +``` + +### Installing your Okteto instance + +Install the latest version of Okteto by running: + +```console +helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +After a few seconds, all the resources will be created. The output will look something like this: + +``` +Release "okteto" has been installed. Happy Helming! +NAME: okteto +LAST DEPLOYED: Thu Mar 26 18:07:55 2020 +NAMESPACE: okteto +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +1. Create the following DNS record, pointing it to the NGINX controller service External-IP: +- "*.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto + +2. Create the following DNS record, pointing it to the Buildkit service External-IP: +- "buildkit.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto + +3. Once you create both DNS entries you can access your Okteto instance at this URL: +https://okteto.dev.example.com +``` + +> You can also install a specific version by including the `--version` argument. + +### Retrieve the Ingress Controller IP address + +We can use the instructions `kubectl` to fetch the address that has been dynamically allocated by GKE to the NGINX Ingress we've just installed and configured as a part of Okteto: + +```console +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, and add it to your DNS for the domain you have chosen to use. In Google Cloud DNS, this is done by creating an `A` record with the name `*`. We also suggest you set the TTL to 1 minute. + +### Retrieve the Buildkit IP address + +You can use `kubectl` to fetch the address that has been dynamically allocated by GKE to the Buildkit instance you've just installed and configured as a part of Okteto: + +```console +kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto +``` + +The output will look something like this: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-buildkit LoadBalancer 10.245.142.73 34.68.230.233 1234:32449/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. This is done by creating an `A` record with the name `buildkit`. + +## Sign in to your Okteto instance + +> **Important**: The default installation uses self-signed certificates. We strongly recommend that you configure Okteto to [bring your own certificates](self-hosted/administration/certificates.mdx) before giving your team access to your instance. + +You can access your Okteto instance at `https://okteto.SUBDOMAIN`. Your account will be automatically created as part of the login process. The first user to successfully log into the instance will be automatically assigned the `administrator` role. diff --git a/versioned_docs/version-1.5/self-hosted/gke/config.yaml b/versioned_docs/version-1.5/self-hosted/gke/config.yaml new file mode 100644 index 000000000..00c286185 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/gke/config.yaml @@ -0,0 +1,27 @@ +email: + +license: + +subdomain: + +auth: + google: + enabled: true + clientId: + clientSecret: + +cluster: + endpoint: + +cloud: + provider: + gcp: + enabled: true + project: + bucket: + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer \ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/guides/application-repository-in-s3.mdx b/versioned_docs/version-1.5/self-hosted/guides/application-repository-in-s3.mdx new file mode 100644 index 000000000..41bd3ab58 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/guides/application-repository-in-s3.mdx @@ -0,0 +1,201 @@ +--- +title: How to Host your Application Repository in S3 +description: Guide on how to host your Application Repository in S3 +id: application-repository-in-s3 +--- + +import Image from '@theme/Image'; + +## Prerequisites + +- An Instance of [Okteto](https://okteto.com/docs/self-hosted/) running in [Amazon Elastic Kubernetes Service](https://aws.amazon.com/eks/) (EKS). +- Helm 3.0+ installed in your local machine +- AWS CLI installed in your local machine +- Access to an AWS account with access to S3, IAMs, and VPCs + +## Create the Repository S3 Bucket + +The charts are going to be stored in an S3 bucket. Create an S3 bucket via the UI or the `aws cli`, in the same region as your EKS cluster. + +``` +$ aws s3api create-bucket --bucket okteto-applications --region us-west-2 --create-bucket-configuration LocationConstraint=us-west-2 +``` + +``` +{ + "Location": "http://okteto-applications.s3.amazonaws.com/" +} +``` + +> This guide will use `okteto-applications` as the name of the bucket and `us-west-2` as the region for the sample commands. Replace accordingly. + +Once the bucket is created, add the following policy, replacing `okteto-applications` with your bucket name. + +``` +cat << EOF > policy.json +{ + "Version": "2012-10-17", + "Statement": [ + { + "Sid": "PublicReadGetObject", + "Action": "s3:GetObject", + "Effect": "Allow", + "Resource": "arn:aws:s3:::okteto-applications/*", + "Principal": "*" + } + ] +} +EOF + +$ aws s3api put-bucket-policy --bucket okteto-applications --policy file://policy.json +``` + +This policy will make the objects in the bucket available to everyone, which is useful for public applications. We will show you how to lock this down in the final part of the guide. + + +## Package the Chart + +Now that we have a functioning repository, we need to add a chart to it. For this guide, we'll use the `hello-okteto-chart` sample. + +Get your local copy of the sample chart by running the command below: + +``` +$ git clone https://github.com/okteto/hello-okteto-chart +``` + +``` +Cloning into 'hello-okteto-chart'... +remote: Enumerating objects: 4, done. +remote: Counting objects: 100% (4/4), done. +remote: Compressing objects: 100% (4/4), done. +remote: Total 4 (delta 0), reused 0 (delta 0), pack-reused 0 +Receiving objects: 100% (4/4), 4.53 KiB | 4.53 MiB/s, done. +``` + +Once we have a chart, the next step is to package it. This will take all the files in the chart and bundle them in a single `tgz` file: + +``` +$ mkdir charts-repo +$ helm package ./hello-okteto-chart -d charts-repo +``` + +``` +Successfully packaged chart and saved it to: charts-repo/hello-okteto-0.1.0.tgz +``` + +Once the package is generated, we'll generate the repository index. Pass the public DNS of your `s3` bucket in the `url` parameter, as shown below: + +``` +helm repo index charts-repo --url https://okteto-applications.s3.amazonaws.com +``` + +Once this command completes, the `charts-repo` folder will contain two files: `index.yaml` and `hello-world-0.1.0.tgz` + +> If you're adding the chart to an existing index, you should also use the `--merge` parameter. Run `helm repo index --help` to learn more. + + +## Publish the Chart + +To publish the chart, we need to upload the files we generated in the previous step to the `s3` bucket. You can do it using the UI, or with the following command: + +``` + aws s3 cp charts-repo s3://okteto-applications/ --recursive +``` + +You can verify that the chart was correctly published by adding the chart repo locally, and searching for the `hello-okteto` chart, as shown below: + +``` +$ helm repo add okteto https://okteto-applications.s3.amazonaws.com +$ helm search repo hello-okteto +``` + +``` +NAME CHART VERSION APP VERSION DESCRIPTION +okteto/hello-okteto 0.1.0 1.0.0 Hello world chart for Okteto +``` + +## Add the Repository to Okteto + +Now that your application is in your private repository, you can add it to Okteto. Login into your instance, click on the `Settings` button in the left, and select the `Repositories` menu in the right. + +Put the URL of your private repository, click on the `+` button, and press the `Save Changes` button. + +Add your repository + +Once added, all the applications in your repository will be available in the Application Catalog. + +> Further instructions are available at /docs/tutorials/repos + +To validate it, click on the `Namespaces` button on the left, and then on the `Deploy` button. Your application will be listed there, ready to be deployed with one click. + +## Protect the Repository + +If you followed the instruction in this guide, your repository will be available across the internet. If your applications are not meant to be publicly available, we recommend that you restrict it so that only your Okteto cluster can access it. + +To do this, we are going to leverage AWS's [VPC Endpoints](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints.html) to only allow the nodes of our EKS cluster to access the S3 bucket without credentials. + +First, we need to know the VPC of the EKS cluster. You can get it through the UI, or by running the command below, using your own cluster name: + +``` +$ aws eks describe-cluster --name cluster-1 +``` + +``` +{ + "cluster": { + ... + "resourcesVpcConfig": { + ... + "vpcId": "vpc-1" + ... + } + ... + } +} +``` + +Second, we need the ID of the routing table we are using. You can get it through the UI, or by running the command below, replacing the values of `vpc-id` with yours: + +``` +aws ec2 describe-route-tables --filters Name=vpc-id,Values=vpc-1 +``` + +Now, we need to create a VPC endpoint. You can create it via the UI, or with the command below, replacing the values of `vpc-id` and `route-table-ids` with yours. +``` +aws ec2 create-vpc-endpoint \ + --vpc-id vpc-1 \ + --service-name com.amazonaws.us-east-1.s3 \ + --route-table-ids "rt-1' +``` + +> More information on this [is available here](https://docs.aws.amazon.com/vpc/latest/userguide/vpc-endpoints-s3.html). + +Finally, we'll update the S3 bucket with a policy that allows access from the VPC endpoint we just created. + +``` +cat << EOF > secure-policy.json +{ + "Version": "2012-10-17", + "Id": "VPCEPolicy", + "Statement": [ + { + "Sid": "Access-to-specific-VPCE-only", + "Effect": "Allow", + "Principal": "*", + "Action": "s3:GetObject", + "Resource": "arn:aws:s3:::okteto-applications/*", + "Condition": { + "StringEquals": { + "aws:sourceVpce": "vpce-0b4c1308c65c27339" + } + } + } + ] +} +EOF + +$ aws s3api put-bucket-policy --bucket +okteto-applications --policy file://secure-policy.json +``` + +With this policy, the charts will only be available to authenticated users, or to resources sending traffic through that VPC Endpoint, like your `EKS` cluster. \ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/client-id.png b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/client-id.png new file mode 100644 index 000000000..927fb4c3e Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/client-id.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/new-app.png b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/new-app.png new file mode 100644 index 000000000..a0cbd7428 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/new-app.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/permissions.png b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/permissions.png new file mode 100644 index 000000000..2e34240c0 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/permissions.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/secrets.png b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/secrets.png new file mode 100644 index 000000000..0edc071da Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/secrets.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/tenant-id.png b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/tenant-id.png new file mode 100644 index 000000000..b60123dde Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/tenant-id.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/with-azure.png b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/with-azure.png new file mode 100644 index 000000000..46e2563f3 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/images/with-azure.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/index.mdx b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/index.mdx new file mode 100644 index 000000000..f8cf472a9 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/guides/azure-active-directory/index.mdx @@ -0,0 +1,104 @@ +--- +title: Use Azure Active Directory as your Authentication Provider +description: Use Azure Active Directory as the authentication provider of your Okteto Self-hosted instance +id: identity-provider-azure +--- + +import Image from '@theme/Image'; +import TiersList from '@theme/TiersList'; + +# Use Azure Active Directory as your Identity Provider + +This guide will walk you through the steps necessary to configure Azure Active Directory as the authentication provider for your Okteto instace. + +Please refer to [Azure's official documentation](https://learn.microsoft.com/en-us/power-apps/maker/portals/configure/configure-openid-settings) on Open ID Connect for more information. + +## Prerequisites + +- An instance of [Okteto](https://okteto.com/docs/self-hosted/). +- [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine. +- Access to an [Azure account](https://portal.azure.com) with permissions to registrate applications in Azure Active Directory. + +## Create an App Registration + +Create a [new app integration](https://portal.azure.com/#view/Microsoft_AAD_RegisteredApps/CreateApplicationBlade/quickStartType~/null/isMSAApp~/false), using the values below: + +

Create the new App Registration

+ +Then, fill in the following values on the “Register an application” window: + +1. Name: The name of your application (e.g. `okteto`) +2. Accounts in this organizational directory only (Default Directory only - Single tenant) +3. Redirect URI: https://okteto.{YOUR_DOMAIN}/auth/callback + +Once the application has been created, save the `Application (client) ID` value. You'll need it to configure your Okteto Instance. + +

Copy the Tenant ID

+ +Copy the `Directory (tenant) ID` value`. You'll need it to configure your Okteto Instance. + +

Copy the Tenant ID

+ +On the left menu, click on "Certificates & secrets". Create a "New client secret" and copy the `Value`. You'll need it to configure your Okteto Instance. + +

Copy the Secret ID and Value

+ +On the lest menu, click on "API permissions" and grant the following permissions: + +

Grant permissions

+ +## Configure Okteto + +Once you have the Okta application ready, you'll need to update the configuration of your Okteto Self-Hosted instance. + +First, update the auth section of your Helm configuration file (e.g. `values.yaml` ) with the values you obtained on the first step of this guide: + +```yaml +auth: + openid: + enabled: true + clientId: $CLIENT_ID + clientSecret: $CLIENT_SECRET + endpoints: + issuer: https://sts.windows.net/$TENANT_ID/ + authorization: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/authorize + mapping: + externalIDKey: email +``` + +> You can also store the value of clientSecret [as a secret directly in Kubernetes](self-hosted/install/deployment.mdx#cloud-provider-secret). + +Then, [upgrade your installation](self-hosted/install/upgrade.mdx) to apply the changes. We recommend that you upgrade to the same version that you already have to minimize the changes and help you troubleshoot any issues. + +Once the upgrade has been completed, go to your instance and click on the **Log In** button to access your instance. If everything is configured correctly, Okteto will now use your Azure Active Directory for user authentication. + +

Log in with Azure Active Directory

+ +### Customize the attributes that Okteto consumes + +By default, Okteto will use the following attributes below when creating a user: + +- `Name` as the display name of the user. +- `Nickname` as the username of the user. +- `Email` as the email. +- `Picture URL` for the user's profile picture. + +If you are not using some of those values, or you want to customize which attributes get mapped, you can customize that by using the `mapping` field inside the `openid` key in your Helm configuration file. + +```yaml +auth: + openid: + enabled: true + clientId: $CLIENT_ID + clientSecret: $CLIENT_SECRET + endpoints: + issuer: https://sts.windows.net/$TENANT_ID/ + authorization: https://login.microsoftonline.com/$TENANT_ID/oauth2/v2.0/authorize + mapping: + externalIDKey: nickname + nameKey: name + emailKey: email + pictureKey: picture +``` + +The value of every key in the `mapping` section must match a `claim` in your Azure Active Directory + OpenID configuration, and it must contain a non-empty value. diff --git a/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-app-created.png b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-app-created.png new file mode 100644 index 000000000..b911858e4 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-app-created.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-new-app-scopes.png b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-new-app-scopes.png new file mode 100644 index 000000000..9e4b35976 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-new-app-scopes.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-new-app.png b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-new-app.png new file mode 100644 index 000000000..47d5db165 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-new-app.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-openid-configuration.png b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-openid-configuration.png new file mode 100644 index 000000000..ffa4a50d0 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/gitlab-openid-configuration.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/with-gitlab.png b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/with-gitlab.png new file mode 100644 index 000000000..46e2563f3 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/gitlab/images/with-gitlab.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/gitlab/index.mdx b/versioned_docs/version-1.5/self-hosted/guides/gitlab/index.mdx new file mode 100644 index 000000000..5420cf7a4 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/guides/gitlab/index.mdx @@ -0,0 +1,105 @@ +--- +title: Use Gitlab as your Authentication Provider +description: Use Gitlab as the authentication provider of your Okteto Self-hosted instance +id: identity-provider-gitlab +--- + +import Image from '@theme/Image'; +import TiersList from '@theme/TiersList'; + +# Use Gitlab as your Identity Provider + +This guide will walk you through the steps necessary to configure Gitlab as the authentication provider for your Okteto instace. + +Please refer to [GitLab's official documentation](https://docs.gitlab.com/ee/integration/openid_connect_provider.html) on Open ID Connect for more information. + +## Prerequisites + +- An instance of [Okteto](https://okteto.com/docs/self-hosted/). +- [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine. +- Access to a [Gitlab account](https://gitlab.com) with permissions to enable and configure OAuth and OpenID. This can either gitlab.com, or self-hosted GitLab. + +:::info +This guide will use https://gitlab.com in the examples. If you're using GitLab self-hosted, replace `gitlab.com` with the URL of your GitLab instance. +::: + +## Create the GitLab Application + +Create a new OAuth application integration, using the values below: + +- Name: "okteto" +- Redirect URI: "https://okteto.${YOUR_DOMAIN}.com/auth/callback" +- Unselect the `Confidential` checkbox +- Select the following scopes: + - `openid` + - `profile` + - `email` + +

Create the new GitLab App

+

Set the OpenID Scopes for the GitLab App

+ +Once the application has been created, copy the values of the `Application ID` and the `Secret`. You'll need them to configure your Okteto Instance. + +

Copy the Application ID and Secret from the success page

+ +Finally, browse to https://gitlab.com/.well-known/openid-configuration, and copy the values of `issuer` and `authorization_endpoint`. You'll need this to finish configuration of your Okteto instance. + +

Copy the issuer and authorization_endpoint from the openid configuration response

+ + + +## Configure Okteto + +Once you have your GitLab configuration ready, you'll need to update the configuration of your Okteto Self-Hosted instance. + +First, update the auth section of your Helm configuration file (e.g. `values.yaml` ) with the values you obtained on the first step of this guide: + +```yaml +auth: + openid: + enabled: true + clientId: $CLIENT_ID + clientSecret: $CLIENT_SECRET + endpoints: + issuer: "https://gitlab.com" + authorization: "https://gitlab.com/oauth/authorize" + mapping: + externalIDKey: email +``` + +> You can also store the value of clientSecret [as a secret directly in Kubernetes](self-hosted/install/deployment.mdx#cloud-provider-secret). + +Then, [upgrade your installation](self-hosted/install/upgrade.mdx) to apply the changes. We recommend that you upgrade to the same version that you already have to minimize the changes and help you troubleshoot any issues. + +Once the upgrade has been completed, go to your instance and click on the **Log In** button to access your instance. If everything is configured correctly, Okteto will now use Gitlab for user authentication. + +

Log in with Gitlab

+ +### Customize the attributes that Okteto consumes + +By default, Okteto will use the following attributes below when creating a user: + +- `Name` as the display name of the user. +- `Nickname` as the username of the user. +- `Email` as the email. +- `Picture URL` for the user's profile picture. + +If you are not using some of those values, or you want to customize which attributes get mapped, you can customize that by using the `mapping` field inside the `openid` key in your Helm configuration file. + +```yaml +auth: + openid: + enabled: true + clientId: $CLIENT_ID + clientSecret: $CLIENT_SECRET + endpoints: + issuer: "https://gitlab.com" + authorization: "https://gitlab.com/oauth/authorize" + mapping: + externalIDKey: nickname + nameKey: name + emailKey: email + pictureKey: picture +``` + +The value of every key in the `mapping` section must match a `claim` in your Gitlab OpenID configuration, and it must contain a non-empty value. You can see the available claims in the `claims_supported` section of https://gitlab.com/.well-known/openid-configuration. diff --git a/versioned_docs/version-1.5/self-hosted/guides/images/add-repository.png b/versioned_docs/version-1.5/self-hosted/guides/images/add-repository.png new file mode 100644 index 000000000..2aff0ee7b Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/images/add-repository.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/add-user.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/add-user.png new file mode 100644 index 000000000..091366c8e Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/add-user.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/assignment.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/assignment.png new file mode 100644 index 000000000..bc0421674 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/assignment.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-app.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-app.png new file mode 100644 index 000000000..50d801a4a Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-app.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-web-app-integration-2.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-web-app-integration-2.png new file mode 100644 index 000000000..c570d659d Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-web-app-integration-2.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-web-app-integration.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-web-app-integration.png new file mode 100644 index 000000000..a6a4e3199 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/new-web-app-integration.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/profile-details.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/profile-details.png new file mode 100644 index 000000000..0368c5113 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/profile-details.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/profile.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/profile.png new file mode 100644 index 000000000..5059cff03 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/profile.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/secrets.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/secrets.png new file mode 100644 index 000000000..83db3f93e Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/secrets.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/well-known.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/well-known.png new file mode 100644 index 000000000..92214d60a Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/well-known.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/images/with-okta.png b/versioned_docs/version-1.5/self-hosted/guides/okta/images/with-okta.png new file mode 100644 index 000000000..46e2563f3 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/guides/okta/images/with-okta.png differ diff --git a/versioned_docs/version-1.5/self-hosted/guides/okta/index.mdx b/versioned_docs/version-1.5/self-hosted/guides/okta/index.mdx new file mode 100644 index 000000000..e0ccd931c --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/guides/okta/index.mdx @@ -0,0 +1,165 @@ +--- +title: Use Okta as your Authentication Provider +description: Guide on how use Okta as the authentication provider of your Okteto Self-hosted instance +id: identity-provider-okta +--- + +import Image from '@theme/Image'; +import TiersList from '@theme/TiersList'; + +# Use Okta as your Identity Provider + +This guide will walk you through the steps necessary to configure Okta as the authentication provider for your instace of Okteto. + +Please refer to [Okta's official documentation](https://developer.okta.com/docs/concepts/oauth-openid/) on Open ID Connect for more information. + +## Prerequisites + +- An instance of [Okteto](https://okteto.com/docs/self-hosted/). +- [Helm](https://helm.sh/docs/intro/install/) 3.0+ installed in your local machine. +- Access to an [Okta account](https://www.okta.com) with permissions to create Applications. + +## Create the Okta Application + +Create a new app integration, using the values below: + +

Create the new app

+ +Then, fill in the following values on the “New Web App Integration” window: + +1. Name: The name of your app (e.g. Okteto) +2. Grant type: authorization code +3. Sign In Redirect: https://okteto.{YOUR_DOMAIN}/auth/callback +4. Assignments: We recommend you create a dedicated group for Okteto, so you can control who can access your instance from Okta. + +Leave all the other values empty, and press the save button. + +

Create the new app integration

+ +

Create the new app integration

+ +Once the application has been created, copy the ClientID and the Client Secret. You'll need them to configure your Okteto Instance. + +

Copy the client ID and the Client Secret

+ +Assign the users or groups that will have access to Okteto to the application that you just created. + +

Assign the users to the application

+ +By default, Okteto will use the attributes below when creating a user. These will be synchronized when the account is created, and everytime the user logs in. + +- `Name` as the display name of the user. +- `Nickname` as the username of the user. +- `Email` as the email. +- `Picture URL` for the user's profile picture. + +Authentication will fail if the `Nickname` or `Email` property is missing or empty. Please refer to the [Customize the attributes that Okteto consumes](#customize-the-attributes-that-okteto-consumes) section below on how to change the attributes that Okteto will use during authentication and account creation. + +Finally, browse to https://{YOUR_TENANT}.okta.com/.well-known/openid-configuration, and copy the values of `issuer` and `authorization_endpoint`. You'll need this to finish configuration of your Okteto instance. + + +

Get the URLs for authorization

+ +### Update your Users Profile for Okteto + +Okta will send the values set on the user profile as part of the authentication process. If you want to set specific values for Okteto, you can set an Application-specific overrride by going to Directory → People → ${User} → Applications → Okteto → Edit). + +

Update the profile in the application assignment

+ +

Update the profile details in the application assignment

+ +> If you want to sync the profile picture from Okta, you'll need to set the Picture URL property in the dialog shown above. + +## Configure Okteto + +Once you have the Okta application ready, you'll need to update the configuration of your Okteto Self-Hosted instance. + +First, update the auth section of your Helm configuration file (e.g. `values.yaml` ) with the values you obtained on the first step of this guide: + +```yaml +auth: + openid: + enabled: true + clientId: $CLIENT_ID + clientSecret: $CLIENT_SECRET + endpoints: + issuer: $ISSUER_URL + authorization: $AUTHORIZATION_URL +``` + +In our demo instance, this looks like: + +```yaml +... +auth: + openid: + enabled: true + clientId: 0oa76rh0z5zgKG7XXXXX + clientSecret: dTgsfHbYV9tt91Ng4dzvpULw6y7kjJaYxzfXXXXX + endpoints: + issuer: https://dev-6093102.okta.com + authorization: https://dev-6093102.okta.com/oauth2/v1/authorize +... +``` + +> You can also store the value of clientSecret [as a secret directly in Kubernetes](self-hosted/install/deployment.mdx#cloud-provider-secret). + +Then, [upgrade your installation](self-hosted/install/upgrade.mdx) to apply the changes. We recommend that you upgrade to the same version that you already have to minimize the changes and help with your troubleshooting. + +Once the upgrade has been completed, go to your instance and click on the 'Log In' button to access your instance using Okta as the authentication provider. + +

Log in with Okta

+ +### Customize the attributes that Okteto consumes + +By default, Okteto will use the following attributes below when creating a user: + +- `Name` as the display name of the user. +- `Nickname` as the username of the user. +- `Email` as the email. +- `Picture URL` for the user's profile picture. + +If you are not using some of those values, or you want to customize which attributes get mapped, you can customize that by using the `mapping` field inside the `openid` key in your Helm configuration file. + +```yaml +auth: + openid: + enabled: true + clientId: $CLIENT_ID + clientSecret: $CLIENT_SECRET + endpoints: + issuer: $ISSUER_URL + authorization: $AUTHORIZATION_URL + mapping: + externalIDKey: nickname + nameKey: name + emailKey: email + pictureKey: picture +``` + +The value of every key in the `mapping` section must match a `claim` in your Okta + OpenID configuration, and it must contain a non-empty value. + +For example, if you just want to use the `email` instead of the nickname for usernames, use the following configuration: + +```yaml +auth: + openid: + enabled: true + clientId: 0oa76rh0z5zgKG7XXXXX + clientSecret: dTgsfHbYV9tt91Ng4dzvpULw6y7kjJaYxzfXXXXX + endpoints: + issuer: https://dev-6093102.okta.com + authorization: https://dev-6093102.okta.com/oauth2/v1/authorize + mapping: + externalIDKey: email +``` + +## Troubleshooting + +### Log in fails with a 500 error + +This is most likely because the user was not added to the application. Make sure that the user (or group) is assigned to the application that you just created in Okta. + +To fix this, go to Application → Okteto → Assignments and add the required users or groups. + +

Add user to the Okta application

\ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/images/civo-add-a-new-domain-record.png b/versioned_docs/version-1.5/self-hosted/images/civo-add-a-new-domain-record.png new file mode 100644 index 000000000..05a58d681 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/images/civo-add-a-new-domain-record.png differ diff --git a/versioned_docs/version-1.5/self-hosted/images/civo-apikey.png b/versioned_docs/version-1.5/self-hosted/images/civo-apikey.png new file mode 100644 index 000000000..32af7c4ee Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/images/civo-apikey.png differ diff --git a/versioned_docs/version-1.5/self-hosted/images/civo-dns-records.png b/versioned_docs/version-1.5/self-hosted/images/civo-dns-records.png new file mode 100644 index 000000000..8d4c84552 Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/images/civo-dns-records.png differ diff --git a/versioned_docs/version-1.5/self-hosted/images/private-repository.png b/versioned_docs/version-1.5/self-hosted/images/private-repository.png new file mode 100644 index 000000000..d54fcbb0a Binary files /dev/null and b/versioned_docs/version-1.5/self-hosted/images/private-repository.png differ diff --git a/versioned_docs/version-1.5/self-hosted/install/deployment.mdx b/versioned_docs/version-1.5/self-hosted/install/deployment.mdx new file mode 100644 index 000000000..9ce0d8ccb --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/install/deployment.mdx @@ -0,0 +1,296 @@ +--- +title: Deploy your Okteto instance +description: How to Deploy Okteto in your Kubernetes cluster +id: deployment +sidebar_label: Deployment +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Create the Okteto Namespace + +Run the command below to create a namespace for okteto: + +```console +$ kubectl create namespace okteto +``` + +## Configuration file + +Before running `helm install`, we recommend that you create a yaml configuration file with your choices about how to install Okteto. This guide will walk you through the most common options. A complete list of configuration options is [available here](self-hosted/administration/configuration.mdx). + +You can use [this sample configuration file](https://charts.okteto.com/config.yaml) as a starting point. The different configuration settings are explained below. + +### Email + +You'll need to provide the email of the application owner. + +```yaml +email: "admin@example.com" +``` + +### Cluster Endpoint + +This is the public endpoint of your Kubernetes cluster. It will be used by Okteto when generating `Kubeconfig` credentials for your users. + +```yaml +cluster: + endpoint: "https://52.30.32.1" +``` + +### Domain + +The domain (or subdomain) managed by your Okteto installation. + +Your users will be able to access your Okteto instance at `okteto.$SUBDOMAIN`. All ingresses created by okteto will be use it as well (e.g. https://app-$NAMESPACE.$SUBDOMAIN) + +```yaml +subdomain: "example.com" +``` + +### License + +Okteto is free for small teams. You get all the features of [Okteto](self-hosted.mdx) for up to 3 users. + +```yaml +license: XXXXX +``` + +Want to use Okteto with a bigger team? [Let's talk](https://okteto.com/#talktous) + +> You can also use [a secret](self-hosted/install/deployment.mdx#cloud-provider-secret) to store the license. + +### Authentication + +Okteto supports using Bitbucket, GitHub, Google, or OpenID Connect as authentication providers. + +Use the `clientId` and `clientSecret` that you created [in the previous step](self-hosted/install/preparation.mdx#authentication). + + + + +```yaml +auth: + bitbucket: + enabled: true + clientId: OAuth Consumer Key + clientSecret: OAuth Consumer Secret + workspace: my-workspace +``` + +An empty `workspace` field allows any Bitbucket user to authenticate. + + + + +```yaml +auth: + google: + enabled: true + clientId: clientid.apps.googleusercontent.com + clientSecret: clientSecret +``` + + + +```yaml +auth: + github: + enabled: true + clientId: clientID + clientSecret: clientSecret + organization: my-org +``` + +An empty `organization` field allows any GitHub user to authenticate. + + + + +```yaml +auth: + openid: + enabled: true + clientId: clientID + clientSecret: clientSecret + group: my-group + endpoints: + issuer: https://your-provider + authorization: https://your-provider/authorization +``` +An empty `group` field allows any user to authenticate. + +The `issuer` and `authorization` endpoints must match the value returned in the provider config discovery. + +Further configuration settings [are described here](self-hosted/administration/configuration.mdx#auth). + + + +> You can also use [a secret](self-hosted/install/deployment.mdx#cloud-provider-secret) to store the sensitive part of these credentials. + +### Cloud Provider + +Specify the cloud provider you'll use, as well as identity details. + + + + + +```yaml +cloud: + provider: + azure: + enabled: true + storage: + container: "Storage Container Name" + accountName: "Storage Account Name" +``` + + + + +```yaml +cloud: + provider: + aws: + enabled: true + bucket: "Bucket Name" + region: "AWS region" + iam: + accessKeyID: "IAM Access Key" +``` + + + + +```yaml +cloud: + provider: + digitalocean: + enabled: true + region: "Region ID" + space: + name: "Space Name" + accessKeyID: "Space Access Key ID" +``` + + + + +```yaml +cloud: + provider: + gcp: + enabled: true + bucket: "Bucket Name" + project: "Project ID" +``` + + + + +## Cloud Provider Secret + +Create a secret named `okteto-cloud-secret` to store the Cloud Provider credentials created [in the preparation step](self-hosted/install/preparation.mdx#authentication). + + + + + +```console +$ kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=STORAGE_ACCOUNT_ACCESS_KEY +``` + +- `STORAGE_ACCOUNT_ACCESS_KEY`: A storage account access key with read/write permissions to the storage container specified in the configuration. + + + + + +```console +$ kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=IAM_ACCESS_SECRET +``` + +- `IAM_ACCESS_SECRET`: The access secret of an IAM with read/write permissions to the bucket and Route53 zone specified in the configuration. + + + + + +```console +$ kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=ACCESS_KEY +``` + +- `ACCESS_KEY`: The access key of the storage space specified in the configuration. + + + + + +```console +$ kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-file=key=key.json +``` + +- `key.json`: A file containing the key of a service account with read/write permissions to the storage bucket specified in the configuration. + + + + +#### Store Additional Values + +You can also use the `okteto-cloud-secret` 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. + +## Deploy the Okteto Chart + +Run `helm install` to deploy your Okteto instance. In this example, we have named our Helm release okteto. + +```console +$ helm repo add okteto https://charts.okteto.com +$ helm repo update +$ helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +You can also use `--version version` if you would like to install a specific version of Okteto. + +Check the status of the deployment by running `helm status okteto`. + +## Post Install Configuration + +Once the chart is installed, follow the onscreen instructions to finalize the configuration. + +## Initial login + +You can access your Okteto instance by going to https://okteto.$SUBDOMAIN. An account will be automatically created for you as part of the login process. diff --git a/versioned_docs/version-1.5/self-hosted/install/overview.mdx b/versioned_docs/version-1.5/self-hosted/install/overview.mdx new file mode 100644 index 000000000..f7bcb1705 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/install/overview.mdx @@ -0,0 +1,67 @@ +--- +title: Installation Overview +description: How to install Okteto in your own Kubernetes cluster +sidebar_label: Overview +id: overview +--- + +Okteto is a development platform for Kubernetes applications. Build better applications by developing and testing your code directly in your own Kubernetes infrastructure. Give your team the power of the [Okteto Development Platform](index.md), with the control and flexibility of running in your own infrastructure. + +Okteto is free for small teams. You get all the features of [Okteto](self-hosted.mdx) for up to 3 users. + +Want to use Okteto with a bigger team? [Let's talk](https://www.okteto.com/contact/) 😎. + +## Introduction + +Okteto is distributed as a Helm chart. This contains all the required components for the complete Okteto experience. + +Okteto components: + +1. NGINX Ingress +1. Okteto/API +1. Okteto/Buildkit +1. Okteto/Frontend +1. Okteto/Migration +1. Okteto/Registry +1. Okteto/Validation Webhook + +## Quick Installation Guides + +For those looking to get up and running as fast as possible, we provide installation guides for different public cloud providers. These guides walk the user through deploying these charts with default values and basic configuration: + +- [Install Okteto in Amazon Elastic Kubernetes Service](self-hosted/eks.mdx) +- [Install Okteto in Azure Kubernetes Service](self-hosted/aks.mdx) +- [Install Okteto in Civo](self-hosted/civo.mdx) +- [Install Okteto in Google Kubernetes Engine](self-hosted/gke.mdx) +- [Install Okteto in DigitalOcean Kubernetes](self-hosted/digitalocean.mdx) + +## Troubleshooting + +We've done our best to make Okteto easy to install and operate. [The troubleshooting page](self-hosted/install/troubleshooting.mdx) has tips and tricks to help troubleshoot common issues. + +You can also [reach out to support](https://okteto.com/support) if you need assistance. + +## Installation + +The Okteto chart contains all the required dependencies. This guide will walk you through the different options and features available. + +1. [Preparation](self-hosted/install/preparation.mdx) +2. [Deployment](self-hosted/install/deployment.mdx) + +If you are just looking to deploy a Proof of Concept, we recommend you follow our [Quick Installation Guides](#quick-installation-guides) for your first iteration. + +### Upgrading + +Instructions on how to upgrade your Okteto instance [are available here](self-hosted/install/upgrade.mdx). + +Please review [the release notes before upgrading](self-hosted/install/releases.mdx). New features, known issues, and configuration changes will be listed there. + +### Uninstalling Okteto + +To delete an existing release use: + +```console +$ helm delete +``` + +This will delete Okteto, but not the resources created when using it (e.g. namespaces, accounts, deployments, etc...). diff --git a/versioned_docs/version-1.5/self-hosted/install/preparation.mdx b/versioned_docs/version-1.5/self-hosted/install/preparation.mdx new file mode 100644 index 000000000..53ef603c8 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/install/preparation.mdx @@ -0,0 +1,285 @@ +--- +title: Installation Preparation +description: How to install Okteto in your own Kubernetes cluster +id: preparation +sidebar_label: Preparation +--- + +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +## Requirements + +In order to fully install Okteto, you'll need the following: + +- A domain to which you can add a wildcard DNS record +- A Kubernetes cluster +- A working installation of kubectl +- A working installation of Helm v3 +- A Bitbucket, GitHub, or Google OAuth application, or an OpenID Connect application +- Credentials of your Cloud Provider +- A bucket (or equivalent block storage) +- An Okteto License (optional) + +### Domain + +You'll need to have access to a domain to which you can add a wildcard DNS record. + +This can be a root domain (e.g. example.com) or a subdomain (e.g. dev.example.com). +By default, Okteto creates a self-signed certificate to secure communication to the Okteto dashboard, the build service, the registry service, and to all the applications that use [Automatic SSL Endpoints](https://okteto.com/docs/cloud/ssl/). +Follow [this guide](self-hosted/administration/certificates.mdx) if you want to bring your own certificates. + +### Deploy a Kubernetes cluster + +We recommend that you follow your cloud provider's Kubernetes cluster creation guide. +Okteto supports Kubernetes versions 1.21 through 1.23. + +We recommend the following specs: +- v1.23 +- A pool with at least 3 nodes with a minimum of 4CPUs and 16 GB of Memory +- 100 GB per disk + +You'll be using the cluster's API server endpoint when configuring Okteto. + +> Our installation guides assume Okteto will be running in a dedicated cluster. We recommend [contacting our team](https://www.okteto.com/contact/) if you plan on installing Okteto in a cluster with other workloads. + +### Installing kubectl + +Follow the official Kubernetes documentation for [installing kubectl](https://kubernetes.io/docs/tasks/tools/install-kubectl/). + +Be sure to configure your kubectl to talk to your newly minted cluster. + +### Installing Helm v3 + +Follow the official documentation for [installing the latest release of Helm v3](https://helm.sh/docs/intro/install/). + +### Authentication + +Okteto uses OAuth for user authentication. It currently supports GitHub, Google, and OpenID Connect. + + + + +Follow Bitbucket's official documentation on [how to create an OAuth Consumer](https://support.atlassian.com/bitbucket-cloud/docs/use-oauth-on-bitbucket-cloud/). + +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 + + +You'll use the `Key` and `Secret` when installing Okteto. + + + + +> If you are planning on using the GitHub Integration, you should follow [this guide](self-hosted/administration/configuration.mdx#creating-the-github-app). 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](https://developer.github.com/apps/building-oauth-apps/creating-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 +``` + +You'll use the `client ID` and `client Secret` when installing Okteto. + + + + +Follow Google's official documentation on [how to create an OAuth 2.0 Client](https://support.google.com/cloud/answer/6158849?hl=en). + +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 +``` + +You'll use the `client ID`, `client Secret` when installing Okteto. + + + + +Follow your OpenID Connect service provider's documentation on how to create the required application. + +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` + +You'll use the `issuer URL`, `authorization URL`, `client ID`, and `client Secret` when installing Okteto. + +> Okteto doesn't currently support provider-initiated login or logout. + + + + +### Cloud Provider Account + +Okteto needs to perform the following actions on your cloud provider: + +1. Read and Write from block storage (this is used when pulling and pushing images to the registry) + +Please refer to the following documents on how to create the credentials in the different cloud providers: + + + + + +#### Creating an Azure Storage Account + +Follow [these instructions](https://docs.microsoft.com/en-us/azure/storage/common/storage-account-create?tabs=azure-portal) to create a storage account in your Azure Subscription. You'll use the access key when installing Okteto. + +#### Creating a Storage Container + +Okteto uses a Storage Container to store your private images. Follow Azures's [guide on how to create a storage container](https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html) and set its privacy level to private. + +#### Registering your Domain + +Follow [these instructions](https://docs.microsoft.com/en-us/azure/dns/dns-delegate-domain-azure-dns) to register your domain in Azure DNS. + + + + +#### Registering your Domain + +Follow [these instructions](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/dns-configuring.html) to register your domain in Route53. + +Register your domain using the same account used to create your EKS cluster. + +#### Creating an S3 Bucket + +Okteto uses S3 to store your private images. Follow Amazon's [guide on how to create s3 buckets](https://docs.aws.amazon.com/quickstarts/latest/s3backup/step-1-create-bucket.html). Create the bucket in the region as your EKS cluster, and keep it private. + +#### Creating an IAM + +The Okteto Registry needs access to S3 for uploading and downloading your container images. + +We recommend you follow AWS' official documentation on [how to create and manage IAM Users](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) for more information on this. + +Create an `IAM User` with the following actions (replace `YOUR_BUCKET` with your `s3` bucket name): + +``` +{ + "Version": "2012-10-17", + "Statement": [ + { + "Effect": "Allow", + "Action": [ + "s3:ListBucket", + "s3:GetBucketLocation", + "s3:ListBucketMultipartUploads" + ], + "Resource": "arn:aws:s3:::YOUR_BUCKET" + }, + { + "Effect": "Allow", + "Action": [ + "s3:PutObject", + "s3:GetObject", + "s3:DeleteObject", + "s3:ListMultipartUploadParts", + "s3:AbortMultipartUpload" + ], + "Resource": "arn:aws:s3:::YOUR_BUCKET/*" + } + ] +} +``` + +Once the `IAM User` is created, generate a set of Access keys and save them locally. You'll use the keys when installing Okteto. + + + + + +#### Registering your Domain + +Follow [these instructions](https://www.digitalocean.com/docs/networking/dns/how-to/add-domains/#:~:text=To%20add%20a%20domain%20from,field%2C%20then%20click%20Add%20Domain) to register your domain with DigitalOcean. + +Register your domain using the same account used to create your DOK cluster. + +#### Creating a DigitalOcean Space and Access Key + +Okteto uses a Storage Space to store your private images. Follow DigitalOcean's [guide on how to create a storage space and api key](https://www.digitalocean.com/community/tutorials/how-to-create-a-digitalocean-space-and-api-key). Create the space in the same region as your Kubernetes cluster and restrict file listing. + + + + + + +#### Registering your Domain + +Follow [these instructions](https://cloud.google.com/dns/zones/) to create a managed zone in your Google Cloud account. + +Create it in the same project and region as your GKE cluster. + +#### Creating a Google Cloud Storage Bucket + +Okteto uses Google Cloud Storage to store your private images. Follow Google's [guide on how to create storage buckets](https://cloud.google.com/storage/docs/quickstart-console). Create the bucket in the same project and region as your GKE cluster, and keep it private. + +#### Creating a Google Cloud Service Account + +The Okteto Registry needs access to Cloud Storage for uploading and downloading your container images. + +We recommend you follow Google's official documentation on [how to create and manage Service Accounts](https://cloud.google.com/iam/docs/creating-managing-service-accounts) for more information on this. + +You'll need to perform the following tasks: + +1. Create a `Service Account` in the same Google Cloud project as your GKE cluster. +1. Give it the `Storage Object Admin` roles. +1. Create a `JSON` key and save it locally. We'll be using this when installing Okteto. + + + + + +You'll use the credentials when installing Okteto. + +## Deploying Okteto + +With the environment set up and configuration generated, you can now proceed to the [deployment of Okteto](self-hosted/install/deployment.mdx). diff --git a/versioned_docs/version-1.5/self-hosted/install/releases.mdx b/versioned_docs/version-1.5/self-hosted/install/releases.mdx new file mode 100644 index 000000000..b03921e3d --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/install/releases.mdx @@ -0,0 +1,312 @@ +--- +title: Release Notes +description: Release Notes +sidebar_label: Release Notes +id: releases +--- + +## 1.5.0 +14 February, 2023 + +### Features + +- You can now define an [icon for every endpoint in your external resources list](reference/manifest.mdx#icon-string-optional) +- Add support for AWS ECR pushing/pulling with IAM Roles for Service Accounts through [installer.buildCredentialHelpers](self-hosted/administration/configuration.mdx#installer) +- Add support for registry cloud provider storage using: + - [GCP Workload Identity](self-hosted/administration/configuration.mdx#workload-identity) + - [AWS IAM Roles for Service Accounts](self-hosted/administration/configuration.mdx#iam-role-for-service-account-irsa) + +### Improvements + +- Make env var values editable on deploy/redeploy +- Filter repositories results by search term +- Delete button is now disabled in the personal namespace +- Reduced load time when opening Github redeploy dialog +- Added antiAffinity [configuration](self-hosted/administration/configuration.mdx#userpodaffinity) for PODs with label `dev.okteto.com/affinity` +- Added granular definition support for [networkPolicies](self-hosted/administration/configuration.mdx#networkpolicies) created by Okteto. + +### Bugfixes + +- When injecting host alises to go through internal network to buildkit, registry and api, don't duplicate entries for same IP. Instead, pass the list of hostnames for the IP +- Remove non-existent External Resources status that caused Deployments to show as "Deployed" with a red error badge +- "Get Started" button is not active while running a "destroy all" job +- Fix namespace wake up when endpoint requests is sent to paths other than root. +- Keep ingress class on wake if ingress class is different than "sleeping" +- Ignore read only Kubernetes API Extension Servers (e.g. metrics.k8s.io) if unavailable on destroy all job runs. +- When using Divert, some scenarios may cause its ingress configuration to be dropped +- Don't show a pointer cursor type in log lines +- Autopreviews are now being deleted when PR is merged or closed +- Correctly alignment of non private/divert endpoints and repository at resource details section. +- Removed unused configuration values related to cert-manager in the Helm chart +- Fixed issue in the OpenID configuration that prevented using ADFS as the identity provider +- Get claims from access token when `ADFS` resource is given +- Added support for volume snapshots in EKS 1.23 + +## 1.4.2 +February 7, 2023 + +### Bugfixes +- Fixed issue on instances with self-signed certificates or private CA that prevented the destroy all and destroy namespace actions to work properly. + +## 1.4.1 +February 1, 2023 + +### Bugfixes +- Fixed issue that caused the autoscaler to crash when parsing ingresses without the `ingressClassName` attribute. + + +## 1.4.0 +January 19, 2023 + +### Features +- You can now define [external resources](reference/manifest.mdx#external-object-optional) in your Okteto manifest. Use this to include resources that exist outside of your Okteto namespace like databases, message brokers, serverless functions, dashboards, etc. +- You can now show [virtual services](self-hosted/administration/configuration.mdx#virtualservices) endpoints in the Okteto UI +- Update okteto cli version to [2.11.1](https://github.com/okteto/okteto/releases/tag/2.11.1) + +### Improvements +- The commands defined in the `destroy` section of the Okteto manifest will now be executed when destroying a namespace or preview environment +- You can now retry and force namespace deletion in the UI +- When deleting a namespace/preview, its name will appear in the delete pop-up notification +- Sleeping a namespace using the UI now displays a confirmation dialog +- The catalog section of the Deploy dialog now includes a search bar +- The user-provided NGINX configuration snippet (the `nginx.ingress.kubernetes.io/configuration-snippet` annotation) will now get merged with Okteto's configuration snippet +- By default, pod requests are no longer modified by Okteto +- Updated the `crd` configuration in the Helm chart to follow recommended practices for [CRD management](self-hosted/administration/configuration.mdx#crds) +- You can now define [custom affinities](self-hosted/administration/configuration.mdx#affinity) for dev containers and installer jobs in helm config +- You can now define custom resources (requests and limits) for installer jobs +- You can now define tolerations and node selector for the telemetry cronjob +- You can now override the images of the [daemon](self-hosted/administration/configuration.mdx#daemonset) and [autoscaler](self-hosted/administration/configuration.mdx#autoscaler) using the Helm configuration file + + +### Bugfixes +- The branch selector in the Deploy dialog doesn't flicker when the branch is not found +- Fixed issue that prevented private repositories of individual GitHub accounts to be correctly displayed in the Deploy dialog +- Fixed compatibility issues with Azure Active Directory +- Fixed blank screen that sometimes appeared when clicking the "Stop development" button +- Fixed race condition when trying to deploy a development environment that was removed from the catalog +- Ingresses that are not managed for Okteto won't be deleted when a namespace is put to sleep +- Fixed how host aliases are injected in the installer pods as the connection to Okteto's API and registry was not using the internal IPs in some scenarios + + +## 1.3.0 +December 23, 2022 + +### Features + +- [Git Catalog](administration/gitcatalog.mdx) to provide predefined development environments to every developer +- Remove CLI tab from Okteto UI deploy + +### Bugfixes + +- Verification of GitHub usernames is now case insensitive to match GitHub rules +- Fix the race condition that enabled users to modify `repo` field on the GitHub redeploy dialog +- You can now define "resources" for the okteto daemonset component. Use this to ensure that Kubernetes will reserve resources for the `daemonset` +- Fix the race condition that prevented namespace-level resources from being displayed in the UI +- Fix wrong "Last updated" time for development environments in the Okteto UI + +## 1.2.0 +November 25, 2022 + +### Features + +- Update okteto cli version to [2.9.0](https://github.com/okteto/okteto/releases/tag/2.9.0) +- Support for self-signed certificates and private CA with Docker +- Buildkit port is now [configurable](self-hosted/administration/configuration.mdx#buildkit) +- Save costs by allowing to scale down to zero nodes if no user pods are running +- Added [configuration to set PSP and AppArmor](self-hosted/administration/configuration.mdx#podSecurityPolicy) + + +### Improvements +- UI pagination support for GitHub branches list +- Populate oauth errors to the user + + +### Bugfixes + +- Don't show warning when installing okteto on k8s 1.23.x +- Frontend nginx [CVE-2022-40303](https://access.redhat.com/security/cve/CVE-2022-40303)/[CVE-2022-40304](https://access.redhat.com/security/cve/CVE-2022-40304) +- Fix loader icon regression +- Display license related information properly +- Update text in error when using token-based auth +- Persist selfsigned wildcard certificate +- Allow pods to have their own image pull secret +- Added `registry's hostname` to `installer pods` (`/etc/hosts`) pointing to the internal IP, to ensure an internal connection to the component. +- Fix user deletion when there is no owner among the namespace members +- Virtual services are now correctly displayed in the dashboard + +## 1.1.0 +November 2, 2022 + +### Features +- Allow members of a namespace to share it. + +### Improvements +- Allow disabling the autoscaler. +- Support custom labels and annotations in okteto serviceaccounts. +- Allow not checking that the domains of the user's app match the okteto subdomain. +- Support for extra role bindings for every developer account on each namespace. +- Support for keeping pod resources by using `dev.okteto.com/pod-resources: keep` annotation. +- Support for custom ingress class for ingresses created by okteto installation. + + +### Bugfixes +- Check if using volume snapshots to delete a PVC. +- Fix ingress-nginx default wildcard cert. +- Fix internal server error when buildkit is disabled. +- Remove ingress rules for buildkit and localhost. +- Disable validation for custom clusterRole configuration + +## 1.0.0 +September 22, 2022 + +The 1.0.0 comes with two breaking changes, follow our [upgrade guide to 1.x](self-hosted/install/upgrade.mdx#upgrading-to-1x) to reduce the disruption of the service to a minimum. + +### Removal Notice +- Kubernetes [1.19](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.19.md) is no longer supported. + +### Deprecation Notice +- Support for Kubernetes [1.20](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.20.md) has been deprecated and will be removed next release. + +### Features +- Okteto UI now allows users to specify the manifest path when launching a dev environment. + +### Improvements +- Chart has been renamed from "Okteto Enterprise" to "Okteto". +- The cert-manager chart is no longer bundled with Okteto and is no longer installed by default. Okteto now uses a self-signed certificate by default. +- Add support for Kubernetes [1.23](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.23.md). +- Upgrade ingress-nginx to [4.2.1](https://github.com/kubernetes/ingress-nginx/releases/tag/helm-chart-4.2.1). +- Exposed gRPC connection configuration for the BuildKit gRPC [server](/self-hosted/administration/configuration.mdx#buildkit). + +### Bugfixes +- Fixed an issue where PVCs were not being deleted when volumeSnapshots were enabled. + +## 0.15.0 +August 18, 2022 + +### Deprecation Notice +- Deprecate support for Kubernetes [1.19](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.19.md). Support for 1.19 will be dropped in the next release. + +### Improvements +- Add support for Kubernetes [1.22](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.22.md) +- Upgrade Okteto CLI to [2.5.2](https://github.com/okteto/okteto/releases/tag/2.5.2) +- Upgrade Buildkit to [0.10.3](https://github.com/moby/buildkit/releases/tag/v0.10.3) +- Upgrade ingress-nginx to [4.1.3](https://github.com/kubernetes/ingress-nginx/releases/tag/helm-chart-4.1.3) +- Upgrade Reloader dependency to [0.0.118](https://github.com/stakater/Reloader/releases/tag/v0.0.118) +- Enable [user pod preferred affinity](self-hosted/administration/configuration.mdx#userpodaffinity) by default- Eliminated buildkit upgrade failures related to immutable statefulset fields. +- Support the kubernetes endpoints needed by litmus-2.10.2 +- Improve the rollout of public services using rolling updates + + +### Bugfixes +- Delete VolumeSnapshotsContent when VolumeSnapshot is deleted +- Account for non-existing users in GC job when deleting namespaces + + +## 0.14.1 +August 3, 2022 + +### Bugfixes +- Private CAs are now correctly propagated to the worker nodes. + + +## 0.14.0 +July 14, 2022 + +### Features +- Add structured and staged logs for pipelines. Groups logs by stage in the okteto UI. +- Support adding custom environment variables for main Okteto components +- Support adding custom annotations, labels, and environment variables to the pipeline installer jobs +- Display the CLI version used by the pipeline installer jobs in the Okteto UI admin panel +- You can now download the Okteto cluster context from the UI + +### Improvements +- Upgraded Okteto CLI to [2.4.2](https://github.com/okteto/okteto/releases/tag/2.4.2) +- Removed deprecated Google Sign-in JavaScript Platform Library in favor of standard OAuth. More info [here](https://developers.googleblog.com/2021/08/gsi-jsweb-deprecation.html). No action is required. +- Disable the [helm catalog](self-hosted/administration/configuration.mdx#applications) on self-hosted installations by default. This makes installing CRDs not mandatory during cluster creation. +- Improve K8S rolling update process for Okteto API deployment + + +### Bugfixes +- The webhook will not redeploy snapshots as part of an update operation. +- Pipelines are now able to push and pull charts to the internal repository +- The deploy button is now disabled in the UI while requests are in-flight. This was causing double deploys in some scenarios. +- Fixed memory leak caused by not freeing up some resources after closing the connection when streaming the logs. +- Pipelines now show the correct initial date in the logs + + +## 0.13.0 +Jun 16, 2022 + +### Features +- Add Access Control to [Volume Snapshots](self-hosted/administration/volume-snapshots.mdx) +- Add link to the [Community website](https://community.okteto.com) in the help menu. +- Inject `OKTETO_NAMESPACE` and `OKTETO_DOMAIN` environment variables in every pod +- Remove Namespace limit on licenses + +### Improvements +- Upgrade Okteto CLI to [2.3.3](https://github.com/okteto/okteto/releases/tag/2.3.3) +- Upgrade Okteto registry to [2.8.1](https://github.com/distribution/distribution/releases/tag/v2.8.1) +- Better deduplication in secrets query. Prioritize user secrets over cluster secrets. +- Handle PVC update in the mutating webhook. Fixes Okteto CLI issue [#2599](https://github.com/okteto/okteto/issues/2599) +- Upgrade crypto package. Fixes [CVE-2022-27191](https://access.redhat.com/security/cve/CVE-2022-27191) +- Upgrade frontend nginx server to alpine 1.22. Fixes [CVE-2022-27405](https://access.redhat.com/security/cve/CVE-2022-27405) + +### Bugfixes +- Fix panic in Preview Environment query for repos with invalid format +- Fix component running state calculation for pods with many retries. They previously stayed in the error state. +- Fix UI bug with Pull Request names in Preview environment list for non github URLs. + +## 0.12.0 +May 19, 2022 + +### Improvements +- Okteto daemonset no longer mounts host volumes nor runs in privilege mode +- Add support for [GKE workload identity](https://cloud.google.com/kubernetes-engine/docs/concepts/workload-identity) +- Use `ingressClassName` field for ingresses instead of the deprecated `kubernetes.io/ingress.class` annotation +- Add [network quotas](self-hosted/administration/configuration.mdx#quotas) for okteto up +- Invalid ingresses not accepted by the nginx ingress controller are now caught by the webhook +- Deploying daemonset is no longer allowed by default +- Ingresses are put to sleep alongside all other namespace resources and automatically wake by with incoming requests +- Improve pipeline jobs lifecycle and properly handle timeouts. Logs for pipelines that time out are no longer lost +- Account for "ready" container condition to check if a component is healthy +- Decouple computing overloaded nodes from the autoscaler +- Allow users to type in custom branch name for Github repository in the deploy modal +- Add delete button to preview list +- Fix inaccesible modal elements on small screens +- Upgrade to Okteto CLI 2.2.2 +- Upgrade ingress-nginx helm chart to 4.1.0 + +### Bugfixes +- Fix a panic in the mutation webhook for pods with no labels +- Minor UI fixes for deploy's branch selector + +### Breaking changes +- Ingresses using the `kubernetes.io/ingress.class` annotation will be automatically updated by the okteto webhook and saved as `spec.ingressClassName` with the annotation removed +- Okteto Pipelines are executed relative to the path where manifest is located. All relative paths in the manifest will use the context of the subfolder where the manifest is defined + +## 0.11.1 +May 6, 2022 + +### Bugfixes +- Provides a buildkit update for addressing authentication issues when building images. + +## 0.11.0 +April 7, 2022 + +### Features +- Add support for [Okteto Manifest v2](reference/manifest.mdx) +- Allow [custom affinities](self-hosted/administration/configuration.mdx#affinities) in application pods +- Allow to "Wake" previews from the Okteto UI +- Add support for [Buildkit HPA](self-hosted/administration/configuration.mdx#buildkit) (Horizontal Pod Autoscaler) + +### Improvements +- Avoid placing okteto components in overloaded nodes if used in a single node pool +- Reduce Buildkit liveness initial delay from 5m to 10s +- Add resource quotas to jobs and cronjobs +- Migrate cronjobs to use batch/v1 GV as per v1.25 [deprecation guide](https://kubernetes.io/docs/reference/using-api/deprecation-guide/#v1-25). Backwards compatibility still given for kubernetes versions < 1.21. +- Display current Okteto version in Admin view +- Pipeline installer can deploy from "okteto-compose.yml" files + +### Bugfixes +- Automatically reload mutation webhook when internal certificates expire +- Fix service resource creating with NodePort defined diff --git a/versioned_docs/version-1.5/self-hosted/install/troubleshooting.mdx b/versioned_docs/version-1.5/self-hosted/install/troubleshooting.mdx new file mode 100644 index 000000000..70165ecba --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/install/troubleshooting.mdx @@ -0,0 +1,57 @@ +--- +title: Troubleshoot your Okteto instance +description: Questions and answers to common issues when installing or upgrading your Okteto instance +sidebar_label: Troubleshooting +id: troubleshooting +--- + +## UPGRADE FAILED: “okteto” has no deployed releases + +This error will occur on your second install/upgrade if your initial install failed. If the first instal failed, delete the existing install before trying again: + +``` +helm uninstall okteo +``` + +## Registry opods keep restarting + +This can happen when the pods can't read/write from your cloud storage bucket. Double check that the cloud IAM you created has read/write access to the specified bucket. + +## Deployment pipelines stay in "progressing" forever + +This can happen for several reasons, among others, the installer job couldn't be started due to an error in Kubernetes API, or due to an overload in the cluster. +In order to find out what the problem is, there's a way to list all the jobs and pods for a specific pipeline. + +You need the pipeline name (it is the name displayed on Okteto UI) and the namespace where it is deployed. With that information, you can get jobs and pods running these commands: + +```console +kubectl get jobs -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindylopez --namespace=okteto +``` + +```console +kubectl get pods -l=dev.okteto.com/pipeline-name=movies -l=dev.okteto.com/pipeline-namespace=cindylopez --namespace=okteto +``` + +## Using a Custom CNI + +If you're using a custom CNI on your cluster then there may be some additional configuration needed for webhooks. +In certain cases the CNI used on the worker nodes is not the same as the CNI used by the control plane and host networking will need to be used for webhooks. +In addition, the ports may need to be changed to avoid collisions. + +The Okteto Webhook is configured by setting`webhook.hostNetwork` to `true`. The ports are set with `webhook.port`. +More information on the Okteto Webhook configuration can be found [here](self-hosted/administration/configuration.mdx#webhook). + +## Docker Hub credentials misconfiguration + +As you can [configure your own Docker Hub account](self-hosted/administration/configuration.mdx#privateregistry) in Okteto, it could happen that the credentials are not properly set. If that is the case, kubelet won't be able to pull public images from Docker Hub, which can be an important issue in the cluster. + +If this ever happens in your cluster, there is a way to fix it: +- [Update the container image used by the daemonset pods](self-hosted/administration/configuration.mdx#daemonset). **Important note**, use a container registry different than Docker Hub to pull the image without credential problems. For example, you can use `ghcr.io/okteto/busybox`. +- Change or remove the credentials for the Docker Hub registry. +- [Upgrade your cluster](self-hosted/install/upgrade.mdx) with the new configuration. + +After this, the Okteto daemonset will be able to configure the right credentials for Docker Hub. Once you verify everything is working, you can restore the original base image for the Okteto daemonset. + +## We are here to help + +[Reach out to us](https://community.okteto.com/), we're always happy to help! \ No newline at end of file diff --git a/versioned_docs/version-1.5/self-hosted/install/upgrade.mdx b/versioned_docs/version-1.5/self-hosted/install/upgrade.mdx new file mode 100644 index 000000000..cd6298edb --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/install/upgrade.mdx @@ -0,0 +1,117 @@ +--- +title: Upgrade your Okteto instance +description: How to upgrade your Okteto instance +sidebar_label: Upgrade +id: upgrade +--- + +## Upgrade your Okteto Instance + +To upgrade a new release, modify the `config.yaml` with your desired changes and then use: + +```console +$ helm repo update +$ helm upgrade okteto/okteto -f config.yaml --namespace=okteto --version +``` + +For example: +```console +$ helm repo update +$ helm upgrade okteto okteto/okteto -f config.yaml --namespace=okteto --version 0.9.x +``` +*You can use `helm ls` to find the name of your release.* + +Please review [the release notes](self-hosted/install/releases.mdx) before upgrading. New features, known issues, and configuration changes will be listed there. + +## Upgrading to 1.x + +Okteto 1.x has two major breaking changes that you need to be aware of before upgrading: + +- Support for Kubernetes 1.19 has been removed, and 1.20 is deprecated. +- The helm chart has been renamed from `okteto-enterprise` to `okteto`. All the resources created by the chart will have `okteto` as their prefix instead of `okteto-enterprise`. This change will cause all resources to be recreated upon upgrade. Depending on your cloud provider and your networking configuration, you might need to update the DNS entry of the [build service](self-hosted/administration/configuration.mdx#buildkit) after upgrading your Okteto instance. +- The helm chart doesn't install [cert-manager](https://cert-manager.io/) by default. + +We recommend that you follow the steps below to reduce the disruption of the service to a minimum: + +#### Before upgrade + +Skip this step if you are [bringing your own certificates](self-hosted/administration/certificates.mdx). +Check if this is the case by seeing that the wildcard creation is disabled in the Okteto helm values configuration: + +``` +wildcardCertificate: + create: false +``` + +If Okteto was generating the certificates for you, run the following command from your command line to make sure `helm upgrade` doesn't remove the existing cert-manager issuer and certificates: + +``` +kubectl -n okteto annotate issuer okteto-okteto-enterprise helm.sh/resource-policy=keep +kubectl -n okteto annotate certificate default-ssl-certificate helm.sh/resource-policy=keep +``` + +Then, add the following configuration to your Okteto helm values file to use the existing certificate: + +``` +wildcardCertificate: + create: false + name: default-ssl-certificate + +ingress-nginx: + controller: + extraArgs: + default-ssl-certificate: $(POD_NAMESPACE)/default-ssl-certificate +``` + +> Keeping the same `issuer` and `certificate` reduces moving parts during the upgrade, but we recommend you to [bring your own certificate](self-hosted/administration/certificates.mdx) once the Okteto upgrade has been complete succesfully. + +#### Upgrade Okteto + +Run the following commands to upgrade your Okteto instance: + +``` +helm repo update +``` + +``` +helm upgrade --install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +#### After upgrade + +Use `kubectl` to get the new address of the build service: + +```console +kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto +``` + +The output will look something like this: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-buildkit LoadBalancer 10.245.142.73 a519c8b3b27f95...elb.amazonaws.com 1234:32449/TCP 5m +``` + +Update your DNS configuration with the `EXTERNAL-IP` address. + +If you are [bringing your own certificates](self-hosted/administration/certificates.mdx), your Okteto instance is now fully upgraded. The rest of the guide doesn't apply to your configuration. + +## Install cert-manager + +Okteto will remove the instance of `cert-manager` that was installed by older versions of the helm chart. If you plan on using `cert-manager` as your certificate provider, you'll need to install it manually in your cluster using the instructions below: + +``` +helm repo add jetstack https://charts.jetstack.io +``` + +``` +helm repo update +``` + +``` +helm install cert-manager jetstack/cert-manager --namespace=okteto --version=v1.10.2 --set global.podSecurityPolicy.enabled=true +``` + +Once installed, cert-manager will continue to renew your existing certificates. +Please refer to [their docs](https://cert-manager.io/docs/) if you run into any installation or certificate renewal issues. + diff --git a/versioned_docs/version-1.5/self-hosted/offline.mdx b/versioned_docs/version-1.5/self-hosted/offline.mdx new file mode 100644 index 000000000..62a92bf81 --- /dev/null +++ b/versioned_docs/version-1.5/self-hosted/offline.mdx @@ -0,0 +1,232 @@ +--- +title: Okteto Offline Installation +description: How to install and manage Okteto in an offline environment +id: offline +--- + +This guide will show you how to install Okteto onto Azure Kubernetes Service (AKS). We'll be focusing exclusively on AKS in order to keep it as simple as possible. + +## Requirements + +In order to fully install Okteto, you'll need the following: + +- A subdomain to which you can add a wildcard DNS record +- A Kubernetes cluster +- A working installation of kubectl +- A working installation of Helm v3 +- An OAuth application +- An Azure Storage Container +- An Okteto license (optional) + +### Subdomain + +You'll need access to a subdomain to which you can add a wildcard DNS record, such as dev.example.com. + +This guide will assume that your domain is registered in [AzureDNS](https://docs.microsoft.com/en-us/azure/dns/dns-overview). Other DNS services can be used, but aren't covered here. + +### Deploy a Kubernetes cluster + +We recommend that you follow Azure's [cluster creation guide](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough). +Okteto supports Kubernetes versions 1.21 through 1.23. + +We recommend the following specs: +- v1.23 +- A pool with at least 3 `Standard D4` nodes +- 250 GB per Standard SSD Managed Disk + +You'll be using the cluster's API server endpoint when configuring Okteto. +Run the following command to obtain your cluster's API server endpoint: + +``` +kubectl config view --minify | grep server +``` + +> Our installation guides assume Okteto will be running in a dedicated cluster. We recommend [contacting our team](https://www.okteto.com/contact/) if you plan on installing Okteto in a cluster with other workloads. + +### Installing kubectl + +Follow Azure's documentation for [installing kubectl](https://docs.microsoft.com/en-us/azure/aks/kubernetes-walkthrough#connect-to-the-clusterl). Once installed, configure `kubectl` to talk to your new cluster. + +### Installing Helm v3 + +Follow the official documentation for [installing the latest release of Helm v3](https://helm.sh/docs/intro/install/). + +### Creating the OAuth application + +> Okteto supports OAuth providers like Google, GitHub, or OpenID Connect to handle user authentication. For this guide, we'll focus on using GitHub. All the supported configuration settings [are described here](self-hosted/administration/configuration.mdx#auth). + + +> If you are planning on using the GitHub Integration, you should follow [this guide](self-hosted/administration/configuration.mdx#creating-the-github-app). 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](https://developer.github.com/apps/building-oauth-apps/creating-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 +``` + +You'll use the `Client ID` and `Client Secret` when installing Okteto. + +### Creating an Azure Storage Container + +Okteto uses a storage container to store your private images. Follow Azure's [guide on how to create a storage container](https://docs.microsoft.com/en-us/azure/storage/blobs/storage-blobs-introduction). Create the bucket in the region as your AKS cluster, and keep it private. + +You'll need the Account Name and a Storage Account Key when installing Okteto. + +## Adding the Okteto Helm repository + +You'll need to add the Okteto repository in order to be able to install Okteto: + +```console +helm repo add okteto https://charts.okteto.com +helm repo update +``` + +### Getting your Okteto License + +Okteto is free for up to 3 users without a license. +You can also sign on for the [free trial](https://www.okteto.com/free-trial/) to give access up to 100 users for a month. + +## Installing Okteto + +### Create the Okteto Namespace + +Run the following command to create a namespace to install Okteto in: + +```console +$ kubectl create namespace okteto +``` + +### Configuring your Okteto instance + +Create a Kubernetes secret with the Storage Account Access Key you created before: + +```console +kubectl create secret generic okteto-cloud-secret --namespace=okteto --from-literal=key=STORAGE_ACCOUNT_ACCESS_KEY +``` + +Download a copy of the [Okteto AKS configuration file](https://www.okteto.com/docs/self-hosted/aks/config.yaml), open it, and update the following values: + +- Your `email` +- Your `license` (optional) +- A `subdomain` +- `clientId` and `clientSecret` of the OAuth Application you created +- You GitHub `organization`. An empty `organization` field permits any user to log in. +- Your cluster's API server endpoint +- The name of the `storage container` you created +- The `Storage Account Name` + +For example: + +```yaml +email: admin@example.com +license: 1234567890ABCD== +subdomain: dev.example.com +cluster: + endpoint: "https://XXXXXX.aks.microsoft.com" + +auth: + github: + enabled: true + clientId: ae8924d074d8c8809999 + clientSecret: ABCD90598b706d5342f07cce18fee5e5da391234 + organization: my-org + +cloud: + provider: + azure: + enabled: true + storage: + container: "okteto-container" + accountName: "okteto-storage-account" + +buildkit: + ingress: + enabled: false + service: + type: LoadBalancer +``` + +### Installing your Okteto instance + +Install the latest version of Okteto by running: + +```console +helm install okteto okteto/okteto -f config.yaml --namespace=okteto +``` + +After a few seconds, all the resources will be created. The output will look something like this: + +``` +Release "okteto" has been installed. Happy Helming! +NAME: okteto +LAST DEPLOYED: Thu Mar 26 18:07:55 2020 +NAMESPACE: okteto +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +1. Create the following DNS record, pointing it to the NGINX controller service External-IP: +- "*.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/name=ingress-nginx,app.kubernetes.io/component=controller --namespace=okteto + +2. Create the following DNS record, pointing it to the Buildkit service External-IP: +- "buildkit.dev.example.com" + +You can retrieve the External IP by running: + kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto + +3. Once you create both DNS entries you can access your Okteto instance at this URL: +https://okteto.dev.example.com +``` + +> You can also install a specific version by including the `--version` argument. + +### Retrieve the Ingress Controller IP address + +We can use the instructions `kubectl` to fetch the address that has been dynamically allocated by AKS to the NGINX Ingress we've just installed and configured as a part of Okteto: + +```console +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 a519c8b3b27f94...aks.microsoft.com 80:30795/TCP,443:32481/TCP,1234:30885/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address and add it to your DNS for the domain you have chosen to use. In AzureDNS, this is done by creating an `A` record with the name `*`, pointing to the IP of the Load Balancer. + +### Retrieve the Buildkit IP address + +You can use `kubectl` to fetch the address that has been dynamically allocated by AKS to the Buildkit instance you've just installed and configured as a part of Okteto: + +```console +kubectl get service -l=app.kubernetes.io/instance=okteto,app.kubernetes.io/component=buildkit --namespace=okteto +``` + +The output will look something like this: + +``` +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +okteto-buildkit LoadBalancer 10.245.142.73 a519c8b3b27f95...aks.microsoft.com 1234:32449/TCP 5m +``` + +You'll need to take the `EXTERNAL-IP` address, and add it to your DNS for the domain you have chosen to use. This is done by creating an `A` record with the name `buildkit`. + +## Sign in to your Okteto instance + +> **Important**: The default installation uses self-signed certificates. We strongly recommend that you configure Okteto to [bring your own certificates](self-hosted/administration/certificates.mdx) before giving your team access to your instance. + +You can access your Okteto instance at `https://okteto.SUBDOMAIN`. Your account will be automatically created as part of the login process. The first user to successfully log into the instance will be automatically assigned the `administrator` role. diff --git a/versioned_docs/version-1.5/tutorials/aws-lambda.mdx b/versioned_docs/version-1.5/tutorials/aws-lambda.mdx new file mode 100644 index 000000000..e96b4bb4c --- /dev/null +++ b/versioned_docs/version-1.5/tutorials/aws-lambda.mdx @@ -0,0 +1,97 @@ +--- +title: Deploy an AWS Lambda function in your Development Environment +description: Deploy an AWS Lambda function in your Development Environment +sidebar_label: AWS Lambda Functions with Okteto +id: aws-lambda +--- + +import Image from '@theme/Image'; + +This tutorial will show you how to deploy a development environment in Okteto that contains an AWS Lambda function with Okteto. + +## Prerequisites + +- Access to an Okteto instance +- Access to an AWS account with the permissions to create IAMs +- The Docker CLI +- Access to a container registry + +## Step 1: Create an IAM user + +The IAM user that you use with AWS SAM must have sufficient permissions to make necessary AWS service calls and manage AWS resources. + +The following permissions will enable you to complete this tutorial: +- AWSCloudFormationFullAccess +- IAMFullAccess +- AWSLambda_FullAccess +- AmazonAPIGatewayAdministrator +- AmazonS3FullAccess + +Once the user has been created, [generate a set of access keys](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_credentials_access-keys.html), and save them file locally. + +In order for the installer to be able to use this keys, we need to upload them to Okteto as secrets. Follow [the instructions listed here](cloud/secrets.mdx) to do it. Use `AWS_ACCESS_KEY_ID` as the name for the secret that contains the access key, and `AWS_SECRET_ACCESS_KEY` as the name for the secret that contains the secret access key.  + +You can add them both as an [Admin Secret](administration/dashboard.mdx#secrets-section) (if you want everyone in your instance to be able to use them), or a [User Secret](cloud/secrets.mdx). + +## Step 2: Build a custom installer image + +We are going to use the SAM CLI to build and deploy our AWS Lambda function. [SAM](https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html) is a open-source framework that you can use to build serverless applications in AWS. + +You can directly install the SAM CLI in your Okteto manifest. However, this will make every deployment slower than it needs to be. Instead, we recommend that you create your own installer image with `sam`(and any other tool you might need) preinstalled. + +First, build a Docker image using the Dockerfile below: + +```  +FROM okteto/pipeline-runner:1.0.0 + +RUN apt-get update && \ + apt-get install unzip && \ + curl -o /tmp/awscli-exe-linux-x86_64.zip -L https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip && \ + unzip /tmp/awscli-exe-linux-x86_64.zip -d /tmp/aws-cli && \ + sh /tmp/aws-cli/aws/install && \ + aws --version && \ + curl -o /tmp/aws-sam-cli-linux-x86_64.zip -L https://github.com/aws/aws-sam-cli/releases/latest/download/aws-sam-cli-linux-x86_64.zip && \ + unzip /tmp/aws-sam-cli-linux-x86_64.zip -d /tmp/sam-installation && \ + sh /tmp/sam-installation/install && \ + sam --version +``` + +Building this Dockerfile will result in an image that contains everything on the `okteto/pipeline-installer` image, as well as the AWS CLI and the SAM CLI. + +[Follow this document](self-hosted/administration/custom-installer-image.mdx) to update the configuration of your Okteto instance. + +## Step 3: Create your Okteto manifest + +In this tutorial, we are only going to deploy the AWS Lambda function to keep it simple. In the real world, you'd typically include both containers and AWS Lambda functions as part of your Development Environment. + +In order to deploy a function in Okteto, you need to create an Okteto manifest similar to the one below: + +```yaml +# okteto.yaml +deploy: +- sam build +- sam deploy --no-confirm-changeset --no-fail-on-empty-changeset --s3-prefix "${OKTETO_NAMESPACE}" --stack-name "${OKTETO_NAMESPACE}-okteto-lambda" --resolve-s3 +- aws cloudformation describe-stacks --region us-east-1 --stack-name ${OKTETO_NAMESPACE}-okteto-lambda --query "Stacks[0].Outputs[0].OutputValue" --output text > lambda-url +- cat lambda-url +destroy: + - sam delete --no-prompts --stack-name "${OKTETO_NAMESPACE}-okteto-lambda" --region us-east-1 +``` + +Details: +- The first line of the `deploy` command is going to build the lambda using the source code available in your repository. +- The second line will deploy it. We use `--no-confirm-changeset`  and `--no-fail-on-empty-changeset` to ensure that the function can be redeployed if it already exists. +- In the third line we use the AWS CLI to get the URL of the newly created lambda function, and we store it as a file. You can then use the content of this file to pass the information to the rest of your applications as an environment variable or as a build argument. + +## Step 4: Launch your Development Environment + +Commit the Okteto manifest that we created in the previous step to your repository, and push the changes to a remote branch. Then, deploy your Development Environment [directly from the Okteto dashboard](cloud/deploy-from-git.mdx). + +After a few seconds, your Development Environment will be fully deployed and your AWS Lambda function will be up and running. Every time you redeploy the Development Environment, the AWS Lambda function will be recreated with your latest code. + +The source code used on this tutorial [is available here](https://github.com/okteto/aws-lambda). + +## Next steps + +Congratulations, you just deployed **your first AWS Lambda function in Okteto** 🚀. + +Head over to our getting started guides for [Go](samples/golang.mdx), [ASP.NET](samples/aspnetcore.mdx), [Java](samples/java.mdx), [Node.js](samples/node.mdx), [PHP](samples/php.mdx), [Python](samples/python.mdx), or [Ruby](samples/ruby.mdx) to see how to integrate it with the rest of your applications. diff --git a/versioned_docs/version-1.5/tutorials/compose-getting-started.mdx b/versioned_docs/version-1.5/tutorials/compose-getting-started.mdx new file mode 100644 index 000000000..2407697a8 --- /dev/null +++ b/versioned_docs/version-1.5/tutorials/compose-getting-started.mdx @@ -0,0 +1,135 @@ +--- +title: Docker Compose on Kubernetes with Okteto +description: Docker Compose on Kubernetes with Okteto +sidebar_label: Docker Compose on Kubernetes with Okteto +id: compose-getting-started +--- + +import Image from '@theme/Image'; + +This tutorial will show you how to develop an application with Okteto using Docker Compose files. +[Docker Compose](reference/docker-compose.mdx) are for developers who don't want to deal with the complexities of Kubernetes manifests. +Okteto implements and extends the [Compose Specification](https://github.com/compose-spec/compose-spec) to make it easy to develop Docker Compose applications on Kubernetes. + +## Prerequisites + +- Install the Okteto CLI. Follow this [guide](cloud/okteto-cli.mdx) if you haven't done it yet. +- Configure Access to your Okteto Cloud Namespace [using the Okteto CLI](cloud/credentials.mdx#download-your-kubernetes-credentials-using-the-okteto-cli) or [using the Okteto Cloud UI](cloud/credentials.mdx#download-your-kubernetes-credentials-from-the-okteto-cloud-ui). + +## Step 1: Launch your Development Environment + +Get a local version of the Sample App by executing the following commands: + +```console +$ git clone https://github.com/okteto/compose-getting-started +$ cd compose-getting-started +``` + +The Sample App is a simple web application implemented using Python, with Redis for storage. +The `docker-compose.yml` file defines the components of the Sample App: + +```yaml +services: + vote: + build: vote + scale: 2 + environment: + - FLASK_ENV=development + command: python app.py + ports: + - 8080:8080 + volumes: + - ./vote:/src + + redis: + image: redis + ports: + - 6379 + volumes: + - redis:/data + +volumes: + redis: +``` + +The equivalent Kubernetes manifests would have more than 300 lines of yaml! + +Deploying the Sample App is as simple as executing this command: + +```console +$ okteto deploy --wait +``` + +```console + i Using pchico83 @ cloud.okteto.com as context + ✓ Deploying compose + i Endpoints available: + - https://vote-cindy.cloud.okteto.net/ + ✓ Development environment 'compose-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +The `deploy` command will create the necessary deployments, services, persistent volumes, and ingress rules needed to run the Sample App. Cool no 😎? + +Open your browser and go to the URL of your development environment, shown as part of the `okteto deploy` logs (https://vote-cindy.cloud.okteto.net/ in this case). + +## Step 2: Developing time! + +In order to hot-reload your application in your remote development environment, run the this command: + +```console +$ okteto up vote +``` + +``` + i Using pchico83 @ cloud.okteto.com as context + i Development environment 'compose-getting-started' already deployed. + i To redeploy your development environment run 'okteto deploy' or 'okteto up vote --deploy' + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Context: cloud.okteto.com + Namespace: cindy + Name: vote + Forward: 8080 -> 8080 + + * Serving Flask app 'app' (lazy loading) + * Environment: development + * Debug mode: on + * Running on all addresses. + WARNING: This is a development server. Do not use it in a production deployment. + * Running on http://10.8.35.69:8080/ (Press CTRL+C to quit) + * Restarting with stat + * Debugger is active! + * Debugger PIN: 838-277-059 +``` + +From this moment, all you code changes will be immediatelly synched and hot-reloaded by your development environment. +For example, open the `vote/app.py` file in your IDE and modify the voting options on lines 16-17. + +```python +def getOptions(): + option_a = "Local development" + option_b = "Cloud development" +``` + +Save your changes. Check the output of your development environment: + +```console + * Detected change in '/src/app.py', reloading + * Restarting with stat + * Debugger is active! + * Debugger PIN: 838-277-059 +``` + +Access the URL of your application again. +Your code changes were instantly applied. No commit, build, or push required! + + +## Next steps + +Congratulations, you just developed **your first application in Okteto Cloud** 🚀. + +Read the docs for the [Docker Compose](reference/docker-compose.mdx) and the [available Okteto CLI commands](reference/cli.mdx) to learn more about developing your Docker Compose application on Okteto. + +Head over to our getting started guides for [Go](samples/golang.mdx#step-4-debug-directly-in-okteto-cloud), [ASP.NET](samples/aspnetcore.mdx#step-4-debug-directly-in-okteto-cloud), [Java](samples/java.mdx#step-4-debug-directly-in-okteto-cloud), [Node.js](samples/node.mdx#step-4-debug-directly-in-okteto-cloud), [PHP](samples/php.mdx#step-4-debug-directly-in-okteto-cloud), [Python](samples/python.mdx#step-4-debug-directly-in-okteto-cloud), or [Ruby](samples/ruby.mdx#step-4-debug-directly-in-okteto-cloud) to see how to configure Okteto to live-update your application with different programming languages and **debuggers**. diff --git a/versioned_docs/version-1.5/tutorials/getting-started-with-okteto.mdx b/versioned_docs/version-1.5/tutorials/getting-started-with-okteto.mdx new file mode 100644 index 000000000..f7e8a8231 --- /dev/null +++ b/versioned_docs/version-1.5/tutorials/getting-started-with-okteto.mdx @@ -0,0 +1,295 @@ +--- +title: Getting Started with Okteto +description: Getting Started with Okteto +sidebar_label: Getting Started with Okteto +id: getting-started-with-okteto +--- + +import Image from '@theme/Image'; + +This tutorial provides a step by step guide to configure an [Okteto Manifest](reference/manifest.mdx). + +## Overview + +The tutorial is composed of the following steps: + +- Step 1: Code the Hello World application +- Step 2: Define a Dockerfile for building the Docker image of the Hello World application +- Step 3: Create Kubernetes manifests to deploy the Hello World application on Okteto Cloud +- Step 4: Generate your Okteto manifest +- Step 5: Launch your Development Environment +- Step 6: Configure a Remote Development Container +- Step 7: Develop on your Remote Development Container + +Let's get started! + +## Step 1: Code the Hello World application + +We will use a simple Hello World application to illustrate how to configure an Okteto Manifest. +The Hello World application is a simple web service that responds "Hello World!" to every request. +It's written in Go, but Okteto can be used with any application that runs on Kubernetes. + +First, make a new directory called `hello-world` and move inside it: + +```console +$ mkdir hello-world +$ cd hello-world +``` + +Create a new file under the name `main.go` with the following content: + +```golang +package main + +import ( + "fmt" + "net/http" +) + +func main() { + fmt.Println("Starting hello-world server...") + http.HandleFunc("/", helloServer) + if err := http.ListenAndServe(":8080", nil); err != nil { + panic(err) + } +} + +func helloServer(w http.ResponseWriter, r *http.Request) { + fmt.Fprint(w, "Hello world!") +} +``` + +`main.go` implements a Golang web server that listens on port 8080 and responds to every Http request with the message *Hello world!* + +Next, initialize your go module running the following command: + +```console +$ go mod init go-getting-started +``` + +## Step 2: Define a Dockerfile for building the Docker image of the Hello World application + +You need to build a Docker image and push it to a Docker registry before Okteto Cloud can run your application. + +To do that, you need to define a `Dockerfile`. +A `Dockerfile` file is a sequence of instructions to build the Docker image of your application. +If you're not familiar with Docker, we strongly recommend you [learn about it](https://scotch.io/tutorials/getting-started-with-docker). + +Open a new file under the name `Dockerfile` with the following content: + +```Dockerfile +FROM golang:buster + +WORKDIR /app +ADD . . +RUN go build -o app + +EXPOSE 8080 +CMD ["./app"] +``` + +## Step 3: Create Kubernetes manifests to deploy the Hello World application on Okteto Cloud + +To deploy an application to Okteto Cloud, you need to define it using Kubernetes manifests. + +Let's start by creating a new folder for the Kubernetes manifests: + +```console +$ mkdir k8s +``` + +When you use a Kubernetes manifest, you tell Kubernetes how you want your application to run. This time, you'll create a deployment object. Create a new file `k8s/deployment.yaml` with the following content: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: hello-world +spec: + selector: + matchLabels: + app: hello-world + replicas: 1 + template: + metadata: + labels: + app: hello-world + spec: + containers: + - name: hello-world + image: okteto.dev/hello-world:latest + ports: + - containerPort: 8080 +``` + +The deployment manifest has three main sections: + +- `metadata` defines the name for your deployment. +- `replicas` defines how many copies of it you want running. +- `template` tells Kubernetes what to deploy, and what labels to add. In this case, a single container, with the `okteto.dev/hello-world:latest` image we will build in our Okteto Pipeline, listening on port 8080, and with the `app: hello-world` label. Note that this label is the same used in the `selector` section. + +> If you want to know more about Kubernetes deployment objects, check the [official docs](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). + +You'll now need a way to access your application. You can expose an application on Kubernetes by creating a service object. Create a new file called `k8s/service.yaml` with the following content: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hello-world +spec: + type: LoadBalancer + ports: + - name: http + port: 8080 + selector: + app: hello-world +``` + +The service manifest has four main sections: + +- `metadata` tells Kubernetes how to name your service +- `type` tells Kubernetes how you want to expose your service. In this case, it will expose it externally through a Load Balancer. In you want to **expose your application using ingress**, check the [docs](cloud/ssl.mdx#bring-your-own-ingress). +- `ports` tells Kubernetes which ports you want to expose +- `selector` tells Kubernetes how to direct traffic. In this case, any pod with the `app: hello-world` label will receive traffic. + +> Kubernetes manifests can get complex to manage. As your application grows, we recommend you pack your application using [Helm](https://helm.sh/). + +You now have everything ready to define the Okteto Manifest of the Hello World application. + +> When writing your Kubernetes manifests, take into account the [multitenant Kubernetes restrictions](https://okteto.com/docs/cloud/multitenancy/) that we have in place to make Okteto Cloud a secure environment to run your applications. + +## Step 4: Generate your Okteto manifest + +You can automate the deployment of the Hello World application with an Okteto Manifest to provide a one-click deployment experience for anyone in your team or your open source community. +To define your Okteto Manifest, create a new file `okteto.yml` with the following content: + +```yaml +build: + hello-world: + image: okteto.dev/hello-world:latest + context: . + dockerfile: Dockerfile +deploy: + - kubectl apply -f k8s +``` + +The Okteto Manifest has a `build` section to define how to build the image of my application. + +The Okteto Manifest also has a `deploy` section to define the sequence of commands to deploy the Hello World application. +In this case, it deploys the Hello World application using `kubectl` and the Kubernetes manifests you created on Step 2. + +You can make use of tools such as `kubectl`, `helm`, `okteto`, and `kustomize` in your `deploy` commands. + +## Step 5: Deploy your Development Environment + +[Install](cloud/okteto-cli.mdx) the Okteto CLI and configure access to Okteto Cloud: + +```console +$ okteto context use https://cloud.okteto.com +``` + +```console + ✓ Using context cindy @ cloud.okteto.com +``` + +In order to deploy your application, run the following command: + +```console +$ okteto deploy +``` + +```console + i Using cindy @ cloud.okteto.com as context + i Images were already built. To rebuild your images run 'okteto build' or 'okteto deploy --build' + ✓ kubectl apply -f k8s + i Endpoints available: + - https://hello-world-cindy.cloud.okteto.net/ + ✓ Development environment 'go-getting-started' successfully deployed + i Run 'okteto up' to activate your development container +``` + +and that's all, your application will be built and deployed in seconds! + +## Step 6: Configure a Remote Development Container + +Building and deploying your application for each code change can be tedious. +In prevent that, you can configure how to live update your application while you are coding defining a development container. + +To do that, add the following content to your Okteto Manifest: + +```yaml +dev: + hello-world: + image: okteto/golang:1 + command: bash + sync: + - .:/usr/src/app +``` + +The full reference for development containers is [here](reference/manifest.mdx#dev-object-optional). +This is the meaning of the fields we are using here: + +- `image`: the image used by the development container. More information on development images [here](reference/development-environments.mdx). +- `command`: the start command of the development container. +- `sync`: the folders that will be synchronized between your local machine and the development container. + +Now execute the following command to activate your development container: + +```console +$ okteto up +``` + +```console + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Namespace: cindy + Name: hello-world + +Welcome to your development container. Happy coding! +cindy:hello-world app> +``` + +Working in your development container is the same as working on your local machine. +Start the application by running the following command: + +```console +cindy:hello-world app> go run main.go +``` + +```console +Starting hello-world server... +``` + +Go back to the browser, and reload the page to test that your application is running. + +## Step 7: Develop on your Remote Development Container + +Open the file `main.go` in your favorite local IDE and modify the response message on line 17 to be *Hello world from Okteto!*. Save your changes. + +```golang +func helloServer(w http.ResponseWriter, r *http.Request) { + fmt.Fprint(w, "Hello world from Okteto!") +} +``` + +Okteto will synchronize your changes to your development container. +Cancel the execution of `go run main.go` from the development container shell by pressing `ctrl + c`. +Rerun your application: + +```console +cindy:hello-world app> go run main.go +``` + +```console +Starting hello-world server... +``` + +Go back to the browser and reload the page. Your code changes were instantly applied. No commit, build, or push required 😎! + +## Next steps + +Congratulations, you just configured **your first Okteto Manifest** 🚀. + +Head over to our samples for [Go](samples/golang.mdx), [ASP.NET](samples/aspnetcore.mdx), [Java](samples/java.mdx), [Node.js](samples/node.mdx), [PHP](samples/php.mdx), [Python](samples/python.mdx), or [Ruby](samples/ruby.mdx) to see how to use Okteto to live-update your application with different programming languages and **debuggers**. diff --git a/versioned_docs/version-1.5/tutorials/getting-started-with-pipelines.mdx b/versioned_docs/version-1.5/tutorials/getting-started-with-pipelines.mdx new file mode 100644 index 000000000..aff22e59b --- /dev/null +++ b/versioned_docs/version-1.5/tutorials/getting-started-with-pipelines.mdx @@ -0,0 +1,203 @@ +--- +title: Getting Started with Okteto Pipelines +description: Getting Started with Okteto Pipelines +sidebar_label: Getting Started with Okteto Pipelines +id: getting-started-with-pipelines +--- + +import Image from '@theme/Image'; + +This tutorial provides a step by step guide to configure an [Okteto Pipeline](cloud/okteto-pipeline.mdx). +Okteto Pipelines allow anyone on your team or your open source community to deploy a realistic environment for your application on Okteto Cloud in just one click. + +## Overview + +The tutorial is composed of the following steps: + +- Step 1: Code the Hello World application +- Step 2: Define a Dockerfile for building the Docker image of the Hello World application +- Step 3: Create Kubernetes manifests to deploy the Hello World application on Okteto Cloud +- Step 4: Automate the deployment of the Hello World application with an Okteto Pipeline +- Step 5: Deployment time! + +Let's get started! + +## Step 1: Code the Hello World application + +We will use a simple Hello World application to illustrate how to configure an Okteto Pipeline. +The Hello World application is a simple web service that responds "Hello World!" to every request. +It is written in Go, but Okteto can be used with any application that runs on Kubernetes. + +First, make a new directory called `hello-world` and move inside it: + +```console +$ mkdir hello-world +$ cd hello-world +``` + +Create a new file under the name `main.go` with the following content: + +```golang +package main + +import ( + "fmt" + "net/http" +) + +func main() { + fmt.Println("Starting hello-world server...") + http.HandleFunc("/", helloServer) + if err := http.ListenAndServe(":8080", nil); err != nil { + panic(err) + } +} + +func helloServer(w http.ResponseWriter, r *http.Request) { + fmt.Fprint(w, "Hello world!") +} +``` + +`main.go` implements a Golang web server that listens on port 8080 and responds to every Http request with the message *Hello world!* + +Next, initialize your go module running the following command: + +```console +$ go mod init go-getting-started +``` + +## Step 2: Define a Dockerfile for building the Docker image of the Hello World application + +You need to build a Docker image and push it to a Docker registry before Okteto Cloud can run your application. + +To do that, you need to define a `Dockerfile`. +A `Dockerfile` file is a sequence of instructions to build the Docker image of your application. +If you're not familiar with Docker, we strongly recommend you [learn about it](https://scotch.io/tutorials/getting-started-with-docker). + +Open a new file under the name `Dockerfile` with the following content: + +```Dockerfile +FROM golang:buster + +WORKDIR /app +ADD . . +RUN go build -o app + +EXPOSE 8080 +CMD ["./app"] +``` + +## Step 3: Create Kubernetes manifests to deploy the Hello World application on Okteto Cloud + +To deploy an application to Okteto Cloud, you need to define it using Kubernetes manifests. + +Let's start by creating a new folder for the Kubernetes manifests: + +```console +$ mkdir k8s +``` + +When you use a Kubernetes manifest, you tell Kubernetes how you want your application to run. This time, you'll create a deployment object. Create a new file `k8s/deployment.yaml` with the following content: + +```yaml +apiVersion: apps/v1 +kind: Deployment +metadata: + name: hello-world +spec: + selector: + matchLabels: + app: hello-world + replicas: 1 + template: + metadata: + labels: + app: hello-world + spec: + containers: + - name: hello-world + image: okteto.dev/hello-world:latest + ports: + - containerPort: 8080 +``` + +The deployment manifest has three main sections: + +- `metadata` defines the name for your deployment. +- `replicas` defines how many copies of it you want running. +- `template` tells Kubernetes what to deploy, and what labels to add. In this case, a single container, with the `okteto.dev/hello-world:latest` image we will build in our Okteto Pipeline, listening on port 8080, and with the `app: hello-world` label. Note that this label is the same used in the `selector` section. + +> If you want to know more about Kubernetes deployment objects, check the [official docs](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/). + +You'll now need a way to access your application. You can expose an application on Kubernetes by creating a service object. Create a new file called `k8s/service.yaml` with the following content: + +```yaml +apiVersion: v1 +kind: Service +metadata: + name: hello-world +spec: + type: LoadBalancer + ports: + - name: http + port: 8080 + selector: + app: hello-world +``` + +The service manifest has four main sections: + +- `metadata` tells Kubernetes how to name your service +- `type` tells Kubernetes how you want to expose your service. In this case, it will expose it externally through a Load Balancer. In you want to **expose your application using ingress**, check the [docs](cloud/ssl.mdx#bring-your-own-ingress). +- `ports` tells Kubernetes which ports you want to expose +- `selector` tells Kubernetes how to direct traffic. In this case, any pod with the `app: hello-world` label will receive traffic. + +> Kubernetes manifests can get complex to manage. As your application grows, we recommend you pack your application using [Helm](https://helm.sh/). + +You now have everything ready to define the Okteto Pipeline of the Hello World application. + +> When writing your Kubernetes manifests, take into account the [multitenant Kubernetes restrictions](https://okteto.com/docs/cloud/multitenancy/) that we have in place to make Okteto Cloud a secure environment to run your applications. + +## Step 4: Automate the deployment of the Hello World application with an Okteto Pipeline + +You can automate the deployment of the Hello World application with an Okteto Pipeline to provide a one-click deployment experience for anyone in your team or your open source community. +To define your Okteto Pipeline, create a new file `okteto-pipeline.yml` with the following content: + +```yaml +deploy: + - okteto build -t okteto.dev/hello-world:latest + - kubectl apply -f k8s +``` + +The Okteto Pipeline manifest has a `deploy` section to define the sequence of commands to deploy the Hello World application. + +- The first command builds the Docker image of the Hello World application and pushes the image to the [Okteto Registry](cloud/registry.mdx). +Note that `okteto.dev/hello-world:latest` is expanded to the current user image space to make this instruction portable between namespaces. + +- The second command deploys the Hello World application using `kubectl` and the Kubernetes manifests you created on Step 2. + +You can make use of tools such as `kubectl`, `helm`, `okteto`, and `kustomize` in your Okteto Pipeline. +Read the Okteto Pipeline [documentation](cloud/okteto-pipeline.mdx) to learn more about the Okteto Pipeline yaml syntax, available tools, and environment variables that you can use as part of your Okteto Pipeline. + +## Step 5: Deployment time! + +Log into [Okteto Cloud](https://cloud.okteto.com/#/?origin=docs). +Click on the **Deploy** button on the top left of the Okteto Cloud dashboard, select "**Git URL**" as the source +and type the URL of your Git repository to deploy the Hello World application: + +

deploy a git repository

+ +After a few seconds, your application will be ready. You can access the Hello World application by clicking its endpoint: + +Okteto Cloud UI of Hello World app + +> You can make the deployment experience even smoother by adding a [Develop on Okteto](cloud/develop-on-okteto-button.mdx) button to the `README.md` file of your Git repository. + +## Next steps + +Congratulations, you just configured **your first Okteto Pipeline on Okteto Cloud** 🚀. + +We have covered how to deploy realistic environments for cloud-native applications in just one-click. +The full source code used on this tutorial is available [here](https://github.com/okteto/pipeline-getting-started). + +Head over to our samples for [Go](samples/golang.mdx), [ASP.NET](samples/aspnetcore.mdx), [Java](samples/java.mdx), [Node.js](samples/node.mdx), [PHP](samples/php.mdx), [Python](samples/python.mdx), or [Ruby](samples/ruby.mdx) to see how to use Okteto to live-update your application with different programming languages and **debuggers**. diff --git a/versioned_docs/version-1.5/tutorials/images/check.png b/versioned_docs/version-1.5/tutorials/images/check.png new file mode 100644 index 000000000..29969ca89 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/check.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/deploy-from-git.png b/versioned_docs/version-1.5/tutorials/images/deploy-from-git.png new file mode 100644 index 000000000..41e7965a8 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/deploy-from-git.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/deploy-movies.png b/versioned_docs/version-1.5/tutorials/images/deploy-movies.png new file mode 100644 index 000000000..f183fc17a Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/deploy-movies.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/divert-tutorial/arch.png b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/arch.png new file mode 100644 index 000000000..f6ecda41f Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/arch.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/divert-tutorial/catalog-code-edit.gif b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/catalog-code-edit.gif new file mode 100644 index 000000000..46b5cab59 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/catalog-code-edit.gif differ diff --git a/versioned_docs/version-1.5/tutorials/images/divert-tutorial/edited.png b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/edited.png new file mode 100644 index 000000000..83cab0948 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/edited.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/divert-tutorial/original.png b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/original.png new file mode 100644 index 000000000..193196ef0 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/divert-tutorial/original.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/helm-repos.png b/versioned_docs/version-1.5/tutorials/images/helm-repos.png new file mode 100644 index 000000000..6f86bdc71 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/helm-repos.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/message.png b/versioned_docs/version-1.5/tutorials/images/message.png new file mode 100644 index 000000000..6398fccc7 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/message.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/okteto-hello-world-ui.png b/versioned_docs/version-1.5/tutorials/images/okteto-hello-world-ui.png new file mode 100644 index 000000000..b0fb4fa0b Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/okteto-hello-world-ui.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/okteto-stack-ui.png b/versioned_docs/version-1.5/tutorials/images/okteto-stack-ui.png new file mode 100644 index 000000000..2a7f250cc Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/okteto-stack-ui.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/ui-cloud.png b/versioned_docs/version-1.5/tutorials/images/ui-cloud.png new file mode 100644 index 000000000..8b0f935e2 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/ui-cloud.png differ diff --git a/versioned_docs/version-1.5/tutorials/images/ui-movies.png b/versioned_docs/version-1.5/tutorials/images/ui-movies.png new file mode 100644 index 000000000..5c52e4dd4 Binary files /dev/null and b/versioned_docs/version-1.5/tutorials/images/ui-movies.png differ diff --git a/versioned_docs/version-1.5/tutorials/preview-environments.mdx b/versioned_docs/version-1.5/tutorials/preview-environments.mdx new file mode 100644 index 000000000..1d97c2a1f --- /dev/null +++ b/versioned_docs/version-1.5/tutorials/preview-environments.mdx @@ -0,0 +1,115 @@ +--- +title: Preview Environments for your Kubernetes Applications +description: Tutorial on how to automatically create a preview environments for a Kubernetes application using Okteto Cloud and GitHub Actions +sidebar_label: Preview Environments for your Kubernetes Apps +id: preview-environments +--- + +import Image from '@theme/Image'; + +In this section, we'll show you how to automatically create a preview environment for your applications using Okteto Cloud and GitHub Actions. + +## Pre-Requisites +- An [Okteto Cloud account](https://cloud.okteto.com) +- A [GitHub account](https://github.com) + +For this tutorial, we'll be using [this application](https://github.com/okteto/kubernetes-preview-environment). + +## Step 1: Fork the Repository + +Start by forking the [kubernetes-preview-environment](https://github.com/okteto/kubernetes-preview-environment) repository with your GitHub account. + +## Step 2: Create the GitHub Workflow + +To create the preview environments, we're going to use our [GitHub Actions for Okteto Cloud](https://github.com/okteto/actions). + +Creating a preview environment requires performing the following steps: + +1. Login to Okteto Cloud. +1. Deploy a preview environment in Okteto Cloud. +1. Update the PR with the URL of the preview environment. + +The sample repository configured to use [the workflow described above](https://github.com/okteto/kubernetes-preview-environment/blob/master/.github/workflows/preview.yaml). If you want to use this one for your own repositories, all you need to do is to create a `.github/workflow` folder in the root of your repo, and save your workflow file in it. + +The workflow file to create the preview environments looks like this: + +```yaml +# file: .github/workflows/preview.yaml +on: + pull_request: + branches: + - master + +jobs: + preview: + runs-on: ubuntu-latest + steps: + - name: Context + uses: okteto/context@latest + with: + token: ${{ secrets.OKTETO_TOKEN }} + + - name: Deploy preview environment + uses: okteto/deploy-preview@latest + env: + GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }} + with: + name: pr-${{ github.event.number }}-cindylopez + scope: personal + timeout: 15m +``` + +## Step 3: Configure your Okteto API Token + +If you noticed, the workflow uses the `secrets:OKTETO_TOKEN`. We do this so we don't have to commit the token into our repo. Before you run this workflow you need to create the `OKTETO_TOKEN` secret in your repository, with your Okteto API token as the value. + +[Get your Okteto API token here](https://cloud.okteto.com/#/settings/setup). + +Learn more about repository secrets in [GitHub's official documentation](https://help.github.com/en/github/automating-your-workflow-with-github-actions/virtual-environments-for-github-actions#creating-and-using-secrets-encrypted-variables). + +## Step 4: Open a Pull Request + +Once your changes are in your repository, go ahead an open a new pull request. GitHub will receive the event, and it will start your workflow. You can see the status and logs of the workflow in the `checks` section of the pull request. + +

GitHub workflows previews

+ +## Step 5: See your changes live + +After a few seconds, the workflow will update the pull request with the URL of your preview environment. Click on it to see the changes in real time. + +

Preview environment available message with URL

+ +Every time a new commit is pushed to the branch, the same workflow will run, automatically updating the preview environment. + +## Step 6: Cleanup + +The sample repo also includes a workflow [to cleanup the preview environments](https://github.com/okteto/kubernetes-preview-environment/blob/master/.github/workflows/preview-closed.yaml) once the pull request is closed. We recommend you follow this pattern to remove the preview environment after the pull request has been merged. + +``` +# preview-closed.yaml +on: + pull_request: + types: + - closed + +jobs: + closed: + runs-on: ubuntu-latest + steps: + - name: checkout + uses: actions/checkout@master + + - name: Context + uses: okteto/context@latest + with: + token: ${{ secrets.OKTETO_TOKEN }} + + - name: Destroy preview environment + uses: okteto/destroy-preview@latest + with: + name: pr-${{ github.event.number }}-cindylopez +``` + +## Conclusions + +Having automatic preview environments launched along with your pull requests is a great way to do end-to-end testing and to get feedback from your entire team on any code changes. But that's not all. This is also a fantastic way to enable your sales or support team to spin up demo environments without having to depend on the dev team. diff --git a/versioned_docs/version-1.5/tutorials/repos.mdx b/versioned_docs/version-1.5/tutorials/repos.mdx new file mode 100644 index 000000000..726726191 --- /dev/null +++ b/versioned_docs/version-1.5/tutorials/repos.mdx @@ -0,0 +1,42 @@ +--- +title: How to Configure your Custom Helm Repository +description: Tutorial on how to add your own Helm repository to Okteto Cloud +sidebar_label: Configure your Custom Helm Repository +id: repos +--- + +import Image from '@theme/Image'; + +With Okteto Cloud you can deploy [Helm Charts with one click](cloud/deploy-from-helm.mdx). A default list of Helm Charts is provided to get you and your team up and running. + +You can add your own Helm repositories to Okteto Cloud to extend this list. This gives you the same one-click deployment experience with the services that you and your team use. You can use this to simplify onboarding and standarize your dependencies. + +In order to add your Helm Charts, you'll need a Helm chart repository index with at least one published chart. [Follow this guide](https://helm.sh/docs/chart_repository/) to learn how to do it. + +## Add your repository to Okteto Cloud + +On the left side of the Okteto Cloud UI click the **Settings** option. In the new window, click the **Integrations** tab. +The Okteto Cloud UI will show you the Helm repositories you have configured in Okteto Cloud. Click the **Add Repository** button and put the address of your repository: + +

add a Helm repository

+ +The Helm Charts from your Help repository will now be included in the [Deploy from Helm Chart](cloud/deploy-from-helm.mdx) dialog. + +## Suggest default values + +The `values.yaml` file of your Helm Chart contains all the default configuration values for your Helm releases. +This file can be too complex for anyone who is not familiar with your application. +Place a `values-okteto.yaml` file side by side with your `values.yaml` file to show the recommended options to the users. +Okteto will automatically load the `values-okteto.yaml` file and show it in the [Deploy from Helm Chart](cloud/deploy-from-helm.mdx) dialog. + +## Make your chart multi-tenant friendly. + +Okteto Cloud is a multi-tenant environment. It gives you access to a Kubernetes namespace with a few restrictions in place to make it safer and easier to use for everyone. + +Your Helm chart will need to comply with these restrictions to function properly in Okteto Cloud: + +- Your chart cannot create `ClusterRole` or `ClusterRoleBinding` objects. +- `NodePort` and `LoadBalancer` service types are not supported. Okteto Cloud automatically translates `NodePort` or `LoadBalancer` services into ingress rules. More information is [available here](cloud/ssl.mdx). +- The following `Pod` options are not allowed: `privileged`, `hostNetwork`, `allowPrivilegeEscalation`, `hostPID`, `hostIPC`. Volume host paths are not allowed either. + +More information about our multi-tenant policies [is available here](cloud/multitenancy.mdx). diff --git a/versioned_docs/version-1.5/tutorials/webpack.mdx b/versioned_docs/version-1.5/tutorials/webpack.mdx new file mode 100644 index 000000000..cbe421d1a --- /dev/null +++ b/versioned_docs/version-1.5/tutorials/webpack.mdx @@ -0,0 +1,176 @@ +--- +title: Configure Webpack to work inside a container +description: How to adjust your Webpack configuration to work inside a Docker container +sidebar_label: Configure Webpack to work inside a container +id: webpack +--- + +import Image from '@theme/Image'; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + +### Expose webpack's dev server outside the container + +In order to make your app reachable outside the container `webpack-dev-server` must be +configured to use `0.0.0.0` as host. + + +#### webpack.config.js +```js {4} + module.exports = { + //... + devServer: { + host: '0.0.0.0' + } + }; +``` + +### Enable Hot Module Replacement + +If you want to use the Webpack [Hot Module Replacement](https://webpack.js.org/concepts/hot-module-replacement/) +feature to hot reload changes while using the development server, you need to enable it and set the +socket port to `443`. + + + + +#### webpack.config.js +```js {5,8} + module.exports = { + //... + devServer: { + host: '0.0.0.0', + hot: true, + client: { + webSocketURL: { + port: 443 + } + } + } + }; +``` + + + + +#### webpack.config.js +```js {5,6} + module.exports = { + //... + devServer: { + host: '0.0.0.0', + hot: true, + sockPort: 443 + } + }; +``` + + + + +### Host check configuration + +Webpack performs a host check when accessing the server. External access to the server won't be +allowed unless it's properly configured. Check [webpack's dev server documentation](https://webpack.js.org/configuration/dev-server) +for more information. + + + + +You can bypass this check entirely by setting +the [`allowedHosts`](https://webpack.js.org/configuration/dev-server/#devserverallowedhosts) +option to `all`: + +#### webpack.config.js +```js {5} + module.exports = { + //... + devServer: { + host: '0.0.0.0', + allowedHosts: 'all' + } + }; +``` + + + + +You can bypass this check entirely by setting +the [`disableHostCheck`](https://v4.webpack.js.org/configuration/dev-server/#devserverdisablehostcheck) +option to `true`: + +#### webpack.config.js +```js {5} + module.exports = { + //... + devServer: { + host: '0.0.0.0', + disableHostCheck: true + } + }; +``` + + + + +### Watching files + +Webpack uses the file system to get notified of file changes and enable features like hot-reloading. +You might experience file watching issues if your docker image is not compatible with webpack's +file system subsystem. If that's your case, enable the `polling` option: + + + + +#### webpack.config.js +```js {5,6,7} + module.exports = { + //... + devServer: { + host: '0.0.0.0', + watchOptions: { + poll: true // Or you can set a value in milliseconds. + } + } + }; +``` + + + + +#### webpack.config.js +```js {5,6,7} + module.exports = { + //... + devServer: { + host: '0.0.0.0', + watchOptions: { + poll: true // Or you can set a value in milliseconds. + } + } + }; +``` + + + + +Check [webpack's documentation](https://webpack.js.org/configuration/watch/#watchoptions) +for more information about `watchOptions`. diff --git a/versioned_docs/version-1.5/use-cases/docker-compose.mdx b/versioned_docs/version-1.5/use-cases/docker-compose.mdx new file mode 100644 index 000000000..75516c2c5 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/docker-compose.mdx @@ -0,0 +1,13 @@ +--- +title: Develop remotely with Docker Compose +description: Develop remotely with Docker Compose +sidebar_label: Develop remotely with Docker Compose +id: docker-compose +--- + +Our docker-compose integration makes it easy for teams to use Okteto, even when they're not on Kubernetes. + +Remote development with Okteto doesn't requre an active docker session. Instead, you'll have a persistent volume, +instant file syncrhonization, and an accessible public endpoint to view your changes while developing your app locally. + +Learn how to develop docker-compose applications with Okteto [here](https://okteto.com/blog/how-to-develop-docker-compose-applications-remotely-in-okteto-cloud/). \ No newline at end of file diff --git a/versioned_docs/version-1.5/use-cases/ephemeral-development-environments.mdx b/versioned_docs/version-1.5/use-cases/ephemeral-development-environments.mdx new file mode 100644 index 000000000..7419eace5 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/ephemeral-development-environments.mdx @@ -0,0 +1,12 @@ +--- +title: Ephemeral development environments +description: With Okteto's dev environments that mimic production you can be sure that if it works in Okteto, it works in production +sidebar_label: Ephemeral development environments +id: ephemeral-development-environments +--- + +We’ve all been there. You push code to production only to introduce a bug that proves difficult to find. But it worked on your machine, so what happened? + +Often when dealing with several micro dependencies, plus the complexity of Kubernetes, it can be hard to get a realistic picture of what code will actually do when it makes its way to production. You can always push code to staging, but there are even differences in how staging and production operate, and neither mimic the setup on your own machine. + +That’s where Okteto’s realistic dev environments can help. When you can stop relying on your own machine’s setup, and instead have a dev environment that mimics production (without needing to load a million things onto your laptop), you can rest assured that if it works in Okteto, it will work in production. Okteto works with MacOS, Windows, and Linux, and works with any cluster, whether remote or local. diff --git a/versioned_docs/version-1.5/use-cases/hot-reloading.mdx b/versioned_docs/version-1.5/use-cases/hot-reloading.mdx new file mode 100644 index 000000000..1e72e4b26 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/hot-reloading.mdx @@ -0,0 +1,15 @@ +--- +title: See changes as you code with hot reloading +description: Stop wasting time for code to redeploy, snd see changes as you code with Okteto's hot reloading +sidebar_label: See changes as you code with hot reloading +id: hot-reloading +--- + +Waiting for code to redeploy after making changes can waste a lot of your time. + +Thanks to Okteto’s hot reloading, you can see changes in your code as you make them. +This speeds up the inner loop, which means new features can ship faster, +and you won’t have to waste time waiting around just to preview one small change. + +When you save your code, Okteto will automatically synchronize your changes to your development container. +Those changes are automatically detected and hot reloaded. No commit, build, or push required! diff --git a/versioned_docs/version-1.5/use-cases/kubernetes-without-devops.mdx b/versioned_docs/version-1.5/use-cases/kubernetes-without-devops.mdx new file mode 100644 index 000000000..dd091c3b3 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/kubernetes-without-devops.mdx @@ -0,0 +1,16 @@ +--- +title: Kubernetes for your entire team without dedicated DevOps +description: Your entire team can use Kubernetes, without a dedicated DevOps team +sidebar_label: Kubernetes for your entire team without dedicated DevOps +id: kubernetes-without-devops +--- + +Let’s be honest, Kubernetes is not easy to learn, and it can require a dedicated team to operate and manage. +It’s not feasible to assume that all your software engineers are going to be Kubernetes experts, +but they do need access to Kubernetes in order to have a truly production-like development environment. + +That’s where Okteto can help. +Get a realistic development environment for each engineer on your team, onboard new hires quickly, +preview environments, give each developer their own Kubernetes namespace, +garbage collection of unused namespaces and know that if it works in Okteto, it will work in production. + diff --git a/versioned_docs/version-1.5/use-cases/okteto-cli-without-account.mdx b/versioned_docs/version-1.5/use-cases/okteto-cli-without-account.mdx new file mode 100644 index 000000000..2085d3050 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/okteto-cli-without-account.mdx @@ -0,0 +1,14 @@ +--- +title: Okteto CLI works even without a Cloud or Enterprise account +description: Okteto CLI is open source, and can be used with or without a Cloud or Enterprise account +sidebar_label: Okteto CLI works even without a Cloud or Enterprise account +id: okteto-cli-without-account +--- + +Our open source CLI product is popular for a reason. +With all the functionality of Okteto at your fingertips, you can use the pieces of Okteto that are right for your needs, or use it as a launching pad to build something cool of your own. + +We have users that have built their own internal development platforms using Okteto CLI, and it works whether you’re coding in MacOS or Windows. + +Try out the power of Okteto for free and help us become the face of development platforms for cloud native applications. +You can learn more about Okteto CLI and give it a star [here](https://github.com/okteto/okteto/). \ No newline at end of file diff --git a/versioned_docs/version-1.5/use-cases/preview-environments.mdx b/versioned_docs/version-1.5/use-cases/preview-environments.mdx new file mode 100644 index 000000000..41b2b8066 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/preview-environments.mdx @@ -0,0 +1,14 @@ +--- +title: Automated, sharable preview environments +description: Get early feedback from your team with automated, sharable preview environments +sidebar_label: Automated, sharable preview environments +id: sharable-preview-environments +--- + +The easiest way to get early feedback from your team is to share a preview environment that mimics your full-stack application. + +Preview environments allow you to spend time coding and testing, not standing in line for staging, or waiting for the DevOps team to create temporary environments. Having a production-like preview environment also means you can share your work with all members of your team for review, from both technical and non-technical roles. Loop everyone in, and avoid last minute change requests. + +Okteto preview environments can be created automatically with each pull request, and can be available as either personal or global environments (global requires administrator privileges). + +[Learn more about how preview environments can help you code faster](https://okteto.com/preview-environments/). diff --git a/versioned_docs/version-1.5/use-cases/sales-team-demos.mdx b/versioned_docs/version-1.5/use-cases/sales-team-demos.mdx new file mode 100644 index 000000000..afa120cc5 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/sales-team-demos.mdx @@ -0,0 +1,12 @@ +--- +title: Sales team demos +description: Get early feedback from your team with automated, sharable preview environments +sidebar_label: Sales team demos +id: sales-team-demos +--- + +Your sales team is probably not full of full-stack developers, nor would you want it to be. Problem is, when your sales team is responsible for demoing your product to prospects, it can be difficult for them to customize software to show off how your product would work for your potential customer. + +That’s where Okteto can help. Rather than needing to know Kubernetes, Docker, or understand a host of microservices, you can set your sales team up for success by giving them a tool that allows them to easily launch a production-like environment for a potential customer and show them the capabilities. They say a picture is worth a thousand words, and we think a realistic demo could be worth even more when it comes to showcasing what your product can do. + + diff --git a/versioned_docs/version-1.5/use-cases/speed-up-your-computer.mdx b/versioned_docs/version-1.5/use-cases/speed-up-your-computer.mdx new file mode 100644 index 000000000..34a65cb0a --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/speed-up-your-computer.mdx @@ -0,0 +1,13 @@ +--- +title: Speed up your computer and get back time +description: Speed up your computer, get back time, and avoid that dreaded hot laptop with Okteto +sidebar_label: Speed up your computer and get back time +id: speed-up-computer +--- + +How many times have you waited for dependencies to load, or struggled with a sluggish laptop that was weighed down with Docker or Kubernetes taking up space? + +One of the big benefits we hear time and time again from Okteto customers is how quickly they can get to work and also how much time they save not fighting against a sluggish laptop while resources are running out. Not only will Okteto save you time each day, but we also make onboarding new members of your team easier by saving the time you’d spend loading 30+ microservices on each machine. + +Plus, you can avoid that dreaded hot laptop and noisy fan and get back to coding in peace. + diff --git a/versioned_docs/version-1.5/use-cases/test-environments.mdx b/versioned_docs/version-1.5/use-cases/test-environments.mdx new file mode 100644 index 000000000..283610b19 --- /dev/null +++ b/versioned_docs/version-1.5/use-cases/test-environments.mdx @@ -0,0 +1,18 @@ +--- +title: Run end-to-end integration tests with test environments +description: Okteto’s integration environments can be spun up easily for testing and are easily shared with others in your team for collaboration. +sidebar_label: Run end-to-end integration tests with test environments +id: test-environments +--- + +Testing is an integral part of software development. +You can’t push code to production if you don’t know it works, and integration testing is key to making sure that +components of your program work together. + +In integration testing, individual units of a program are tested as a group, +and this type of testing is often carried out by a testing team, not the developers who wrote the code. +Of course, this means that there is always the chance that something could break along the way, +which is why having integration environments on demand to run end to end integration tests can be +so valuable for teams. Okteto’s integration environments can be spun up easily for testing +and are easily shared with others in your team for collaboration. When you run integration tests +you’ll know that if it works in Okteto it will work in production. diff --git a/versioned_docs/version-1.5/using-dev-envs.mdx b/versioned_docs/version-1.5/using-dev-envs.mdx new file mode 100644 index 000000000..a2d9d7c99 --- /dev/null +++ b/versioned_docs/version-1.5/using-dev-envs.mdx @@ -0,0 +1,205 @@ +--- +title: Development Environments +description: In this section, we'll see how you can start using your Development Environment. +sidebar_label: Development Environments +id: using-dev-envs +--- + +import Image from "@theme/Image"; +import Tabs from '@theme/Tabs'; +import TabItem from '@theme/TabItem'; + + +We set configured Okteto CLI with Okteto Cloud in the [previous section](getting-started.mdx). In this section, let's do the fun bits of developing our application in our Development Environment. + +## One Command To Rule Them All + +As part of this guide, we'll be fixing a bug in our sample Movies application. +The application consists of a React frontend and a Node.js backend API. +The frontend uses the REST endpoints of the backend API and loads two different lists of movies based on its response. +Ideally, the application should look like this: + +

+ UI showing the movies app +

+ +But there is a bug in the backend we need to fix to get to this state 🙂 + +We'll be using two different versions of this Movies application to demonstrate this. +One [using Docker Compose](https://github.com/okteto/movies-with-compose) and another one [using Helm charts](https://github.com/okteto/movies-with-helm) to deploy the application. + + + + +```console +$ git clone https://github.com/okteto/movies-with-compose +$ cd movies-with-compose +``` + +```console +$ okteto up +``` + +Since we already have a [Docker compose file](https://github.com/okteto/movies-with-compose/blob/main/docker-compose.yml), +on running `okteto up` you should see Okteto CLI building the required Docker images for your microservices. +When it's done building the images, it will start deploying your application to Okteto Cloud. +You should see the deployed endpoints as part of the output in the CLI: + +```console + ✓ Endpoint 'movies' created + ✓ Volume 'data' created + ✓ Service 'frontend' created + ✓ Service 'mongodb' created + ✓ Service 'api' created + ✓ Service 'init' created + ✓ Service 'movies' created + ✓ Compose 'movies-with-compose' successfully deployed + i Endpoints available: + - https://movies-with-compose-cindylopez.cloud.okteto.net/ +``` + +These endpoints are also shown in the [Okteto Cloud dashboard](https://cloud.okteto.com/): + +

+UI showing the movies app +

+ + + + + +```console +$ git clone https://github.com/okteto/movies-with-helm +$ cd movies-with-helm +``` + +```console +$ okteto up +``` + +Since we already have a [Okteto manifest](https://github.com/okteto/movies-with-helm/blob/main/okteto.yml), +on running `okteto up` you should see Okteto CLI building the required Docker images for your microservices. +When it's done building the images, it will start deploying your application to Okteto Cloud. +You should see the deployed endpoints as part of the output in the CLI: + +```console +Release "movies" does not exist. Installing it now. +NAME: movies +LAST DEPLOYED: Mon Jul 4 11:15:16 2022 +NAMESPACE: pchico83 +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +Success! Your application will be available shortly. + i Endpoints available: + - https://movies-cindylopez.cloud.okteto.net/ + - https://movies-cindylopez.cloud.okteto.net/api +``` + +These endpoints are also shown in the [Okteto Cloud dashboard](https://cloud.okteto.com/): + +

+UI showing the movies app +

+ + + + + +Next, a prompt will ask for the microservice you want to develop. + +```console + Select the development container you want to activate: + Use the arrow keys to navigate: ↓ ↑ → ← + ▸ api + frontend +``` + +Let's go with `api` because we know there's a bug there we need to fix 🙂 + +```console + ✓ Development container 'api' selected + ✓ Persistent volume successfully attached + ✓ Images successfully pulled + ✓ Files synchronized + Context: cloud.okteto.com + Namespace: cindylopez + Name: api + Forward: 9229 -> 9229 + +yarn run v1.22.19 +$ nodemon server.js +[nodemon] 2.0.4 +[nodemon] to restart at any time, enter `rs` +[nodemon] watching path(s): *.* +[nodemon] watching extensions: js,mjs,json +[nodemon] starting `node server.js` +Server running on port 8080. +``` + +Now, you should be able to view your application when you visit their endpoints. +Behind the scenes, the Dev Environment will synchronize your changes everytime you save them. + +## Development Time! + +Visiting the frontend endpoint for the Movies app, something doesn't look right here, does it? + +

+ UI showing the movies app +

+ +The list of movies is the same as Cindy's list. Let's fix that. + +Open your favorite IDE on your local machine and edit line 43 in `/api/server.js` to: + +```javascript + db.collection('watching').find().toArray( (err, results) =>{ +``` + +Now save your changes and go back and refresh the browser. Okteto CLI will automatically synchronize your changes to your development container. Take a look at the development container shell and notice how the changes are detected by [nodemon](https://www.npmjs.com/package//nodemon) and automatically hot reloaded. + +```console +[nodemon] restarting due to changes... +[nodemon] starting `node server.js` +Server running on port 8080. +``` + +See the magic? + + +

+ UI showing the movies app +

+ +Okteto's Development Environment allowed the changes you made to your code locally to reflect immediately on the deployed version of your application. Gone are the troubles of committing and waiting for long CI builds to see how your changes would look in production! + +## Next Steps + +Congratulations! You successfully developed your first application in a Remote Development Environment. + +In this Getting Started guide, we learned how to install Okteto CLI and configure it with Okteto Cloud. Then we saw how you could launch a Development Environment just using a single command: `okteto up`. After that, we fixed a bug in our Movies application using the Dev Environment we had spun up. + +From here, we recommend the following next steps: +- Try launching a Dev Environment for your own application following similar steps to what we saw in this guide. +- If you want to know more things Okteto can help you with, have a look at our [Preview Environments](cloud/preview-environments/overview.mdx). \ No newline at end of file diff --git a/versioned_sidebars/version-1.5-sidebars.json b/versioned_sidebars/version-1.5-sidebars.json new file mode 100644 index 000000000..ac9edb9a1 --- /dev/null +++ b/versioned_sidebars/version-1.5-sidebars.json @@ -0,0 +1,154 @@ +{ + "docs": [ + { + "Welcome": [ + "overview", + { + "type": "category", + "label": "Getting Started", + "items": [ + "getting-started", + "using-dev-envs" + ] + } + ] + }, + { + "Dev Environments": [ + "reference/development-environments", + "cloud/okteto-cli", + { + "type": "category", + "label": "Deploying", + "items": [ + "cloud/deploy-from-git", + "cloud/private-repositories", + "cloud/deploy-from-helm" + ] + }, + "cloud/secrets", + { + "type": "category", + "label": "Exposing Your Application", + "items": [ + "cloud/ssl", + "cloud/private-endpoints", + "cloud/custom-domains" + ] + }, + "cloud/build", + "cloud/registry", + "cloud/use-volume-snapshots", + "cloud/namespaces", + "cloud/credentials", + "cloud/personal-access-tokens", + "reference/file-synchronization", + "reference/ssh-server" + ] + }, + { + "Preview Environments": [ + "cloud/preview-environments/preview-environments", + { + "type": "category", + "label": "For GitHub", + "items": [ + "cloud/preview-environments/dashboard", + "cloud/preview-environments/preview-environments-github" + ] + }, + "cloud/preview-environments/preview-environments-gitlab" + ] + }, + { + "Administration": [ + "administration/dashboard", + "administration/cleanup", + "administration/git-catalog", + { + "type": "category", + "label": "Private Repositories", + "items": [ + "administration/private-repositories/github-app", + "administration/private-repositories/ssh-key" + ] + } + ] + }, + { + "Okteto Self-Hosted": [ + "self-hosted", + { + "type": "category", + "label": "Installation", + "items": [ + "self-hosted/install/overview", + "self-hosted/install/preparation", + "self-hosted/install/deployment", + "self-hosted/install/upgrade", + "self-hosted/install/troubleshooting", + "self-hosted/install/releases" + ] + }, + { + "type": "category", + "label": "Cloud Providers Guides", + "items": [ + "self-hosted/eks", + "self-hosted/aks", + "self-hosted/civo", + "self-hosted/do", + "self-hosted/gke" + ] + }, + { + "type": "category", + "label": "Configuration", + "items": [ + "self-hosted/administration/certificates", + "self-hosted/administration/custom-installer-image", + "self-hosted/administration/configuration", + "self-hosted/administration/github", + "self-hosted/administration/volume-snapshots" + ] + } + ] + }, + { + "References": [ + "reference/cli", + "reference/manifest", + "reference/manifest-migration", + "reference/compose", + "reference/faqs", + "cloud/permissions", + "reference/known-issues" + ] + }, + { + "Tutorials": [ + "tutorials/compose-getting-started", + "tutorials/preview-environments", + "tutorials/webpack", + "tutorials/aws-lambda" + ] + }, + { + "Samples": [ + "samples/aspnetcore", + "samples/golang", + "samples/java", + "samples/node", + "samples/php", + "samples/python", + "samples/ruby", + "samples/more" + ] + }, + { + "type": "link", + "label": "Archives", + "href": "/archives" + } + ] +} diff --git a/versions.json b/versions.json index 2c93140e0..bbfa1438d 100644 --- a/versions.json +++ b/versions.json @@ -1,4 +1,5 @@ [ + "1.5", "1.4", "1.3", "1.2",