The External Resources feature in Okteto is a powerful mechanism that enables you to manage the lifecycle of external resources as part of your Okteto development environment. This means you can define the external resources that comprise your application, include those resources in Okteto's garbage collection process, and even destroy those resources when you finish working with your development environment.
Here are just a few examples of external resources you can use with Okteto:
- A markdown file (e.g. README, API Documentation)
- MongoDB Atlas Instance
- LaunchDarkly environments
- Amazon SQS queues
- Amazon S3 buckets
- Amazon RDS databases
- AWS Lambda Functions
- GCP Cloud Storage
- GCP Cloud Functions
- GCP BigQuery
- Atlassian Confluence Documents
This is not an exhaustive list and only demonstrates the flexibility of this feature. You can include anything as an external resource. You no longer need to use different tools to work on your application in Okteto and you won't need to worry about rogue external resources continuing to run once you are done with your work.
When you configure External Resources in Okteto you can see those resources within the Okteto UI, can click to go directly to those resources in their respective platform, and include them in your Okteto
When you configure the
external section in your Okteto manifest, keep in mind the following:
- You can create a container image that includes any external tools (to Okteto) that you need in order to provision or access your external resources.
- This container image can be included in your Okteto manifest's
- External resources are destroyed when your Okteto namespace is deleted
- External resources are covered by Okteto's garbage collection process
Configuring external resources
Using external resources with Okteto requires configuring three areas of your Okteto manifest:
deploysection to provision your external resources (e.g. call the AWS API to create an s3 bucket)
destroysection to ensure the external resource is destroyed (as appropriate) when your development environment is destroyed
externalsection to populate the Okteto UI and link to the external resource
You can leverage Okteto secrets to pre-define access keys or credentials for these external resources and use those secrets (using the
$SECRET_NAME syntax) within your Okteto manifest.
Admins: We strongly recommend configuring external resource secrets in your admin dashboard to centralize and manage these secrets securely.
When you use an external resource with Okteto it needs to be provisioned like any other resource. If we use the example above of creating an AWS S3 bucket, we could add the following to our Okteto manifest in the
- name: Create an AWS S3 bucket
In this example we're using a script that contains all of the instructions to do the provisioning work and executing that script in this particular stage of the Okteto
You can also use the
OKTETO_BUILD_XXX_IMAGE ENV VAR in the
deploy section to refer to specific container images.
We also need to ensure that the external resources we provision are destroyed when we are finished using our development environment. If we don't include them in the
destroy step, we risk accumulating zombie resources that continue to operate and potentially accrute additional cloud spend. This also allows Okteto to perform this process for you so you never have to worry about it. Here's a sample
destroy section using the same AWS S3 bucket example above:
- name: Delete AWS S3 bucket
Lastly, we want our external resources to be visible in the Okteto UI and accessible to developers working with them. To accomplish this, we need to define the
external section in the Okteto manifest. This section takes the external resources you've provisioned in the
deploy section and makes them a clickable element within the Okteto UI so any developer working in the same namespace can directly access that external resource.
In the example below we're including a README file that documents the external resource we're using (S3 bucket) as well as the S3 bucket itself. You can see additional configuration details in our References section:
- name: readme
- name: bucket
You can also use the dynamic endpoints feature here to provide more flexibility in the URLs.
Every keyword that you see here is opinionated except for
s3:. Those two keywords, the names of the external resources being defined here, can be anything you want them to be. For example, if we want to call the
dundie_award: you can do so. Similarly, you could name
s3: something like
parkour: and it will work just fine.
Whatever name you use to label these resources will be what's shown in the Okteto UI. Choose wisely!
Customizing your external resource UI elements
As you configure your external resources in this section, keep in mind the following definitions:
notes: is used to provide context in the form of a relative link to a markdown file. The contents are displayed in the Okteto UI (see below).
icon: specifies one of several predefined icons you can use when this resource is rendered in the Okteto UI. The current list of supported icons is:
endpoints: contain information on how to access the external resource using:
name:to name the endpoint you're defining
url:to provide the specific url for accessing the resource
The name of the endpoint is used to inject or modify environment variables. In this example, one of those would be:
OKTETO_EXTERNAL_FUNCTIONS_ENDPOINTS_DATA_AGGREGATOR_URL. This is also referred to as Dynamic Endpoints.
All of this information can be found and in a more concise format in our References section.
Using dynamic endpoints with external resources
Dynamic Endpoints is an Okteto feature that lets you define non-static URLs in your Okteto manifest. There are generally three endpoint scenarios:
- A static, unchanging URL that you know and that will remain the same across all users and development environments
- A hybrid URL that may have a static component but incorporate a dynamic one such as a username (e.g. user1.example.com/endpoint)
- A fully dynamic URL that my be completely unique per user
Using the Dynamic Endpoints feature Okteto provides means you can omit the
url: key from a specific external resource in your Okteto manifest and instead compile that URL within the
deploy section (either directly or within an included script).
For example, if have the following
deploy section defined:
- name: Create an AWS SQS queue
We can define the endpoint dynamically within the
deploy.sh script (example here). In simpler terms, the URL is dynamically compiled on this line:
That will compile the appropriate URL, using Okteto environment variables, that specify where a developer in the same namespace will go when they click on the AWS SQS external resource component in the Okteto UI (see below).
Example: Deploy a Development Environment with External Resources
Now that we've walked through a sample of an
external configuration, let's look at using this within the broader context of an application we're working on. You can navigate to our demo repo to follow along if you'd like.
In this example we'll be configuring and deploying a development environment that includes polyglot microservices, an AWS SQS queue, and an S3 bucket.
Okteto CLI 2.14 or newer
An AWS account
An Okteto account
Create the following Okteto secrets:
AWS_ACCESS_KEY_ID: The Acces Key ID of your IAM user
AWS_SECRET_ACCESS_KEY: The Secret Acces Key of your IAM user
AWS_REGION: The region in AWS you would like to use for the external resources
external configuration in this demo. It specifies most attributes except for
url for most of these resources.
- name: readme
- name: queue
- name: bucket
- name: docs
url: keys are missing from most external resource (
api-docs) because they've been defined in the
command section using the Okteto Secrets you defined above and the dynamic endpoints feature.
Alternatively, you could remove the respective
deploy commands and add the
url endpoints here manually, but this is a good example of how flexible the manifest file can be.
Once you've configured the prerequisites, you can deploy this on your Okteto instance:
$ git clone https://github.com/okteto/external-resources-aws
$ cd external-resources-aws
$ okteto context use $OKTETO_URL
$ okteto deploy
okteto deploy command will deploy the Okteto environment, external resources, and anything else defined within your Okteto manifest
deploy section. You can think of this command as the "on button" for your remote cloud development environment within Okteto.
Once the application has been deployed in Okteto, you can work on the
menu microservice by running the command:
okteto up menu. In this specific example, once you've executed this command you'll also need to run
yarn start from the container.
To start the other services in this example (
check) you'll need to run these commands from the container, respectively:
- go run main.go
- python main.py