Skip to main content
Version: 1.47

Okteto BYOC on AWS

Okteto's Bring Your Own Cloud (BYOC) model allows you to run the Okteto Platform in your own AWS account while still benefiting from a fully managed experience. This guide walks you through the steps to set up your AWS environment so Okteto can securely install and manage the platform.

Installation Requirements​

Before you start, ensure the following:

  • The AWS CLI (version 2.15 or later), installed and configured
  • Access to an empty AWS account dedicated to Okteto BYOC
note

AWS Account Requirements:

  • Use a dedicated AWS account exclusively for Okteto. No other workloads should run in this account.
  • Flexible Service Control Policies (SCPs): Okteto requires elevated permissions to provision and for our SRE team to operate infrastructure.
  • Disable VPC Block Public Access. Okteto uses internet-facing load balancers to expose applications. CIDR-based access controls will be available in a future release.

Step 1: Get the AWS IAM Role Assumption External ID​

Contact your Okteto representative to get your unique AWS IAM Role Assumption External ID. Okteto needs it to securely assume a role in your AWS account.

Step 2: Create the IAM Role​

Create a file named trust-policy.json with the following content, or download the trust policy:

trust-policy.json
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Principal": {
"AWS": "585768156265"
},
"Action": "sts:AssumeRole",
"Condition": {
"StringEquals": {
"sts:ExternalId": "REPLACEME"
}
}
}
]
}

Replace REPLACEME with the External ID provided by Okteto.

Create the IAM role from the trust policy with the AWS CLI:

aws iam create-role \
--role-name okteto-byoc-integration \
--assume-role-policy-document file://trust-policy.json

Step 3: Attach the Necessary Policies​

Attach the following policies to the role to give Okteto access to manage the infrastructure:

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/AmazonEC2FullAccess

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/AmazonS3FullAccess

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/AWSCertificateManagerFullAccess

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/CloudWatchLogsFullAccess

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/IAMFullAccess

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/AmazonRoute53FullAccess

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/AWSLambda_FullAccess

aws iam attach-role-policy \
--role-name okteto-byoc-integration \
--policy-arn arn:aws:iam::aws:policy/AmazonAPIGatewayAdministrator

Also add the following inline policies to the role:

{
"Version": "2012-10-17",
"Statement": [
{
"Sid": "EKSFullAccess",
"Effect": "Allow",
"Action": "eks:*",
"Resource": "*"
},
{
"Sid": "KMSFullAccess",
"Effect": "Allow",
"Action": "kms:*",
"Resource": "*"
},
{
"Sid": "STSFullAccess",
"Effect": "Allow",
"Action": "sts:*",
"Resource": "*"
},
{
"Sid": "SNSFullAccess",
"Effect": "Allow",
"Action": "sns:*",
"Resource": "*"
},
{
"Sid": "VisualEditor0",
"Effect": "Allow",
"Action": "aps:*",
"Resource": "*"
}
]
}

Step 4: Share the Role ARN With Your Okteto Representative​

Send the IAM Role ARN to your Okteto representative. They complete the setup and guide you through connecting your cluster to Okteto.

Next Steps​

After you share the IAM Role ARN with your Okteto representative, we take it from there.

Our team:

  • Installs Okteto in your AWS account
  • Makes sure the platform is configured and ready for your team to use

We notify you when the installation is complete and give you onboarding support so your team can start developing with Okteto.

Cluster Management Guidelines​

After Okteto is installed, don't manually modify the EKS cluster or related infrastructure through the AWS Console, AWS CLI, or Terraform.

This includes:

  • EKS cluster configuration (node groups, instance types, scaling configurations)
  • Kubernetes resources in Okteto-managed namespaces
  • Networking, load balancers, or storage resources created by Okteto

Manual changes can cause service degradation and state inconsistencies, and they break our SLA commitments. If you need infrastructure changes, contact your Okteto representative.

For more details, see the Cluster Management Restrictions section in the main BYOC documentation.

Welcome to Okteto BYOC — we're excited to have you on board!