AWS Service Connector
Configuring AWS Service Connectors to connect ZenML to AWS resources like S3 buckets, EKS Kubernetes clusters and ECR container registries.
The ZenML AWS Service Connector facilitates the authentication and access to managed AWS services and resources. These encompass a range of resources, including S3 buckets, ECR container repositories, and EKS clusters. The connector provides support for various authentication methods, including explicit long-lived AWS secret keys, IAM roles, short-lived STS tokens, and implicit authentication.
To ensure heightened security measures, this connector also enables the generation of temporary STS security tokens that are scoped down to the minimum permissions necessary for accessing the intended resource. Furthermore, it includes automatic configuration and detection of credentials locally configured through the AWS CLI.
This connector serves as a general means of accessing any AWS service by issuing pre-authenticated boto3 sessions. Additionally, the connector can handle specialized authentication for S3, Docker, and Kubernetes Python clients. It also allows for the configuration of local Docker and Kubernetes CLIs.
$ zenml service-connector list-types --type aws┏━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━┯━━━━━━━━━━━━━━━━━━━━━━━┯━━━━━━━━━━━━━━━━━━┯━━━━━━━┯━━━━━━━━┓
┃ NAME │ TYPE │ RESOURCE TYPES │ AUTH METHODS │ LOCAL │ REMOTE ┃
┠───────────────────────┼────────┼───────────────────────┼──────────────────┼───────┼────────┨
┃ AWS Service Connector │ 🔶 aws │ 🔶 aws-generic │ implicit │ ✅ │ ✅ ┃
┃ │ │ 📦 s3-bucket │ secret-key │ │ ┃
┃ │ │ 🌀 kubernetes-cluster │ sts-token │ │ ┃
┃ │ │ 🐳 docker-registry │ iam-role │ │ ┃
┃ │ │ │ session-token │ │ ┃
┃ │ │ │ federation-token │ │ ┃
┗━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━┷━━━━━━━━━━━━━━━━━━━━━━━┷━━━━━━━━━━━━━━━━━━┷━━━━━━━┷━━━━━━━━┛Prerequisites
The AWS Service Connector is part of the AWS ZenML integration. You can either install the entire integration or use a PyPI extra to install it independently of the integration:
pip install "zenml[connectors-aws]"installs only prerequisites for the AWS Service Connector Typezenml integration install awsinstalls the entire AWS ZenML integration
It is not required to install and set up the AWS CLI on your local machine to use the AWS Service Connector to link Stack Components to AWS resources and services. However, it is recommended to do so if you are looking for a quick setup that includes using the auto-configuration Service Connector features.
Resource Types
Generic AWS resource
This resource type allows consumers to use the AWS Service Connector to connect to any AWS service or resource. When used by connector clients, they are provided a generic Python boto3 session instance pre-configured with AWS credentials. This session can then be used to create boto3 clients for any particular AWS service.
This generic AWS resource type is meant to be used with Stack Components that are not represented by other, more specific resource types, like S3 buckets, Kubernetes clusters, or Docker registries. It should be accompanied by a matching set of AWS permissions that allow access to the set of remote resources required by the client(s).
The resource name represents the AWS region that the connector is authorized to access.
S3 bucket
Allows users to connect to S3 buckets. When used by connector consumers, they are provided a pre-configured boto3 S3 client instance.
The configured credentials must have at least the following AWS IAM permissions associated with the ARNs of S3 buckets that the connector will be allowed to access (e.g. arn:aws:s3:::* and arn:aws:s3:::*/* represent all the available S3 buckets).
s3:ListBuckets3:GetObjects3:PutObjects3:DeleteObjects3:ListAllMyBucketss3:GetBucketVersionings3:ListBucketVersionss3:DeleteObjectVersion
If set, the resource name must identify an S3 bucket using one of the following formats:
S3 bucket URI (canonical resource name):
s3://{bucket-name}S3 bucket ARN:
arn:aws:s3:::{bucket-name}S3 bucket name:
{bucket-name}
EKS Kubernetes cluster
Allows users to access an EKS cluster as a standard Kubernetes cluster resource. When used by Stack Components, they are provided a pre-authenticated Python Kubernetes client instance.
The configured credentials must have at least the following AWS IAM permissions associated with the ARNs of EKS clusters that the connector will be allowed to access (e.g. arn:aws:eks:{region_id}:{project_id}:cluster/* represents all the EKS clusters available in the target AWS region).
eks:ListClusterseks:DescribeCluster
In addition to the above permissions, if the credentials are not associated with the same IAM user or role that created the EKS cluster, the IAM principal must be manually added to the EKS cluster's aws-auth ConfigMap, otherwise the Kubernetes client will not be allowed to access the cluster's resources. This makes it more challenging to use the AWS Implicit and AWS Federation Token authentication methods for this resource. For more information, see this documentation.
If set, the resource name must identify an EKS cluster using one of the following formats:
EKS cluster name (canonical resource name):
{cluster-name}EKS cluster ARN:
arn:aws:eks:{region}:{account-id}:cluster/{cluster-name}
EKS cluster names are region scoped. The connector can only be used to access EKS clusters in the AWS region that it is configured to use.
ECR container registry
Allows Stack Components to access one or more ECR repositories as a standard Docker registry resource. When used by Stack Components, they are provided a pre-authenticated python-docker client instance.
The configured credentials must have at least the following AWS IAM permissions associated with the ARNs of one or more ECR repositories that the connector will be allowed to access (e.g. arn:aws:ecr:{region}:{account}:repository/* represents all the ECR repositories available in the target AWS region).
ecr:DescribeRegistryecr:DescribeRepositoriesecr:ListRepositoriesecr:BatchGetImageecr:DescribeImagesecr:BatchCheckLayerAvailabilityecr:GetDownloadUrlForLayerecr:InitiateLayerUploadecr:UploadLayerPartecr:CompleteLayerUploadecr:PutImageecr:GetAuthorizationToken
This resource type is not scoped to a single ECR repository. Instead, a connector configured with this resource type will grant access to all the ECR repositories that the credentials are allowed to access under the configured AWS region (i.e. all repositories under the Docker registry URL https://{account-id}.dkr.ecr.{region}.amazonaws.com).
The resource name associated with this resource type uniquely identifies an ECR registry using one of the following formats (the repository name is ignored, only the registry URL/ARN is used):
ECR repository URI (canonical resource name):
[https://]{account}.dkr.ecr.{region}.amazonaws.com[/{repository-name}]
ECR repository ARN :
arn:aws:ecr:{region}:{account-id}:repository[/{repository-name}]
ECR repository names are region scoped. The connector can only be used to access ECR repositories in the AWS region that it is configured to use.
Authentication Methods
Implicit authentication
Implicit authentication to AWS services using environment variables, local configuration files or IAM roles.
This method may constitute a security risk, because it can give users access to the same cloud resources and services that the ZenML Server itself is configured to access. For this reason, all implicit authentication methods are disabled by default and need to be explicitly enabled by setting the ZENML_ENABLE_IMPLICIT_AUTH_METHODS environment variable or the helm chart enableImplicitAuthMethods configuration option to true in the ZenML deployment.
This authentication method doesn't require any credentials to be explicitly configured. It automatically discovers and uses credentials from one of the following sources:
environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY, AWS_SESSION_TOKEN, AWS_DEFAULT_REGION)
local configuration files set up through the AWS CLI (~/aws/credentials, ~/.aws/config)
IAM roles for Amazon EC2, ECS, EKS, Lambda, etc. Only works when running the ZenML server on an AWS resource with an IAM role attached to it.
This is the quickest and easiest way to authenticate to AWS services. However, the results depend on how ZenML is deployed and the environment where it is used and is thus not fully reproducible:
when used with the default local ZenML deployment or a local ZenML server, the credentials are the same as those used by the AWS CLI or extracted from local environment variables
when connected to a ZenML server, this method only works if the ZenML server is deployed in AWS and will use the IAM role attached to the AWS resource where the ZenML server is running (e.g. an EKS cluster). The IAM role permissions may need to be adjusted to allow listing and accessing/describing the AWS resources that the connector is configured to access.
An IAM role may optionally be specified to be assumed by the connector on top of the implicit credentials. This is only possible when the implicit credentials have permissions to assume the target IAM role. Configuring an IAM role has all the advantages of the AWS IAM Role authentication method plus the added benefit of not requiring any explicit credentials to be configured and stored:
the connector will generate temporary STS tokens upon request by calling the AssumeRole STS API.
allows implementing a two layer authentication scheme that keeps the set of permissions associated with implicit credentials down to the bare minimum and grants permissions to the privilege-bearing IAM role instead.
one or more optional IAM session policies may also be configured to further restrict the permissions of the generated STS tokens. If not specified, IAM session policies are automatically configured for the generated STS tokens to restrict them to the minimum set of permissions required to access the target resource. Refer to the documentation for each supported Resource Type for the complete list of AWS permissions automatically granted to the generated STS tokens.
the default expiration period for generated STS tokens is 1 hour with a minimum of 15 minutes up to the maximum session duration setting configured for the IAM role (default is 1 hour). If you need longer-lived tokens, you can configure the IAM role to use a higher maximum expiration value (up to 12 hours) or use the AWS Federation Token or AWS Session Token authentication methods.
Note that the discovered credentials inherit the full set of permissions of the local AWS client configuration, environment variables, or remote AWS IAM role. Depending on the extent of those permissions, this authentication instead method might not be recommended for production use, as it can lead to accidental privilege escalation. It is recommended to also configure an IAM role when using the implicit authentication method, or to use the AWS IAM Role, AWS Session Token, or AWS Federation Token authentication methods instead to limit the validity and/or permissions of the credentials being issued to connector clients.
An AWS region is required and the connector may only be used to access AWS resources in the specified region.
AWS Secret Key
Long-lived AWS credentials consisting of an AWS access key ID and secret access key associated with an AWS IAM user or AWS account root user (not recommended).
This method is preferred during development and testing due to its simplicity and ease of use. It is not recommended as a direct authentication method for production use cases because the clients have direct access to long-lived credentials and are granted the full set of permissions of the IAM user or AWS account root user associated with the credentials. For production, it is recommended to use the AWS IAM Role, AWS Session Token, or AWS Federation Token authentication method instead.
An AWS region is required and the connector may only be used to access AWS resources in the specified region.
If you already have the local AWS CLI set up with these credentials, they will be automatically picked up when auto-configuration is used (see the example below).
AWS STS Token
Uses temporary STS tokens explicitly configured by the user or auto-configured from a local environment.
This method has the major limitation that the user must regularly generate new tokens and update the connector configuration as STS tokens expire. On the other hand, this method is ideal in cases where the connector only needs to be used for a short period of time, such as sharing access temporarily with someone else in your team.
Using other authentication methods like IAM role, Session Token, or Federation Token will automatically generate and refresh STS tokens for clients upon request.
An AWS region is required and the connector may only be used to access AWS resources in the specified region.
AWS IAM Role
Generates temporary STS credentials by assuming an AWS IAM role.
This authentication method still requires credentials to be explicitly configured. If your ZenML server is running in AWS and you're looking for an alternative that uses implicit credentials while at the same time benefits from all the security advantages of assuming an IAM role, you should use the implicit authentication method with a configured IAM role instead.
The connector needs to be configured with the IAM role to be assumed accompanied by an AWS secret key associated with an IAM user or an STS token associated with another IAM role. The IAM user or IAM role must have permission to assume the target IAM role. The connector will generate temporary STS tokens upon request by calling the AssumeRole STS API.
The best practice implemented with this authentication scheme is to keep the set of permissions associated with the primary IAM user or IAM role down to the bare minimum and grant permissions to the privilege-bearing IAM role instead.
An AWS region is required and the connector may only be used to access AWS resources in the specified region.
One or more optional IAM session policies may also be configured to further restrict the permissions of the generated STS tokens. If not specified, IAM session policies are automatically configured for the generated STS tokens to restrict them to the minimum set of permissions required to access the target resource. Refer to the documentation for each supported Resource Type for the complete list of AWS permissions automatically granted to the generated STS tokens.
The default expiration period for generated STS tokens is 1 hour with a minimum of 15 minutes up to the maximum session duration setting configured for the IAM role (default is 1 hour). If you need longer-lived tokens, you can configure the IAM role to use a higher maximum expiration value (up to 12 hours) or use the AWS Federation Token or AWS Session Token authentication methods.
For more information on IAM roles and the AssumeRole AWS API, see the official AWS documentation on the subject.
For more information about the difference between this method and the AWS Federation Token authentication method, consult this AWS documentation page.
AWS Session Token
Generates temporary session STS tokens for IAM users.
The connector needs to be configured with an AWS secret key associated with an IAM user or AWS account root user (not recommended). The connector will generate temporary STS tokens upon request by calling the GetSessionToken STS API.
The STS tokens have an expiration period longer than those issued through the AWS IAM Role authentication method and are more suitable for long-running processes that cannot automatically re-generate credentials upon expiration.
An AWS region is required and the connector may only be used to access AWS resources in the specified region.
The default expiration period for generated STS tokens is 12 hours with a minimum of 15 minutes and a maximum of 36 hours. Temporary credentials obtained by using the AWS account root user credentials (not recommended) have a maximum duration of 1 hour.
As a precaution, when long-lived credentials (i.e. AWS Secret Keys) are detected on your environment by the Service Connector during auto-configuration, this authentication method is automatically chosen instead of the AWS Secret Key authentication method alternative.
Generated STS tokens inherit the full set of permissions of the IAM user or AWS account root user that is calling the GetSessionToken API. Depending on your security needs, this may not be suitable for production use, as it can lead to accidental privilege escalation. Instead, it is recommended to use the AWS Federation Token or AWS IAM Role authentication methods to restrict the permissions of the generated STS tokens.
For more information on session tokens and the GetSessionToken AWS API, see the official AWS documentation on the subject.
AWS Federation Token
Generates temporary STS tokens for federated users by impersonating another user.
The connector needs to be configured with an AWS secret key associated with an IAM user or AWS account root user (not recommended). The IAM user must have permission to call the GetFederationToken STS API (i.e. allow the sts:GetFederationToken action on the * IAM resource). The connector will generate temporary STS tokens upon request by calling the GetFederationToken STS API.
These STS tokens have an expiration period longer than those issued through the AWS IAM Role authentication method and are more suitable for long-running processes that cannot automatically re-generate credentials upon expiration.
An AWS region is required and the connector may only be used to access AWS resources in the specified region.
One or more optional IAM session policies may also be configured to further restrict the permissions of the generated STS tokens. If not specified, IAM session policies are automatically configured for the generated STS tokens to restrict them to the minimum set of permissions required to access the target resource. Refer to the documentation for each supported Resource Type for the complete list of AWS permissions automatically granted to the generated STS tokens.
If this authentication method is used with the generic AWS resource type, a session policy MUST be explicitly specified, otherwise, the generated STS tokens will not have any permissions.
The default expiration period for generated STS tokens is 12 hours with a minimum of 15 minutes and a maximum of 36 hours. Temporary credentials obtained by using the AWS account root user credentials (not recommended) have a maximum duration of 1 hour.
For more information on user federation tokens, session policies, and the GetFederationToken AWS API, see the official AWS documentation on the subject.
For more information about the difference between this method and the AWS IAM Role authentication method, consult this AWS documentation page.
Auto-configuration
The AWS Service Connector allows auto-discovering and fetching credentials and configuration set up by the AWS CLI during registration. The default AWS CLI profile is used unless the AWS_PROFILE environment points to a different profile.
Local client provisioning
The local AWS CLI, Kubernetes kubectl CLI and the Docker CLI can be configured with credentials extracted from or generated by a compatible AWS Service Connector. Please note that unlike the configuration made possible through the AWS CLI, the Kubernetes and Docker credentials issued by the AWS Service Connector have a short lifetime and will need to be regularly refreshed. This is a byproduct of implementing a high-security profile.
Stack Components use
The S3 Artifact Store Stack Component can be connected to a remote AWS S3 bucket through an AWS Service Connector.
The AWS Service Connector can also be used with any Orchestrator or Model Deployer stack component flavor that relies on Kubernetes clusters to manage workloads. This allows EKS Kubernetes container workloads to be managed without the need to configure and maintain explicit AWS or Kubernetes kubectl configuration contexts and credentials in the target environment and in the Stack Component.
Similarly, Container Registry Stack Components can be connected to an ECR Container Registry through an AWS Service Connector. This allows container images to be built and published to ECR container registries without the need to configure explicit AWS credentials in the target environment or the Stack Component.
End-to-end examples
Last updated
Was this helpful?