Gateway on K8s
Akeyless provides a Helm chart to bootstrap the Akeyless Gateway deployment.
New Chart
This guide describe the flow using the newset chart of the Akeyless Gateway.
The Gateway legacy chart docs available here
Prerequisites
-
An Authentication Method with an Access Role to create and manage Secrets, Keys & Targets.
-
Helm Installed
-
K8s Installed with K8s metrics server
-
Minimum 1 vCPU available with 2GB RAM.
-
Network connection to Akeyless SaaS Core Services from your cluster.
-
Network port
8000
on the cluster must be open only for internal network access, allowing access to the following services using the corresponding endpoints:
Service | Endpoint |
---|---|
Gateway Console | /console |
HashiCorp Vault Proxy | /hvp |
Akeyless V1 REST API | /api/v1 |
Akeyless V2 REST API | /api/v2 |
KMIP Server | 5696 |
Helm Chart configuration
- Add the following repository to your Helm repository list:
helm repo add akeyless https://akeylesslabs.github.io/helm-charts
helm repo update
- Fetch the
values.yaml
file from Akeyless repository:
helm show values akeyless/akeyless-gateway > values.yaml
- Use your favorite editor to set the relevant parameters in the
values.yaml
file:
vi values.yaml
Authentication
To set your Gateway with a default Authentication Methods to control the level of access your Gateway instance will have inside your Akeyless account.
The following Authentication Methods are supported for K8s deployments:
API Key Authentication
API Key Authentication Method requires a dedicated K8s Secret to store the corresponding Access Key
where the key name of the secret has to be gateway-access-key
.
Run the following command to create the K8s secret that stores the Access Key
:
kubectl create secret generic access-key \
--from-literal=gateway-access-key=<base64-encoded-Access-Key>
Once the secret is created, set the relevant Access ID
as your gatewayAccessId
and add the name of the K8s Secret that was created as the gatewayCredentialsExistingSecret
:
globalConfig:
gatewayAuth:
gatewayAccessId: <Access ID>
gatewayAccessType: access_key
gatewayCredentialsExistingSecret: access-key
Save the file and proceed with the installation instructions.
CSP IAM Authentication
While running your K8s cluster inside your cloud environment, you can use AWS IAM, GCP, or Azure Active Directory, using machine-to-machine authentication between Akeyless and your Cloud Service Provider with a list of admin users that will be able to manage your Gateway.
Set the gatewayAccessId
with your IAM Authentication Method Access ID
, where you can define a list of users that will be able to manage your Gateway setting the allowedAccessPermissions
field with any other Access ID
of your SAML ,OIDC or an API Key as described here.
AWS IAM
AWS IAM can be used in the following approaches:
-
Instance IAM Role
-
Service Account IAM Role
In both cases, provide your AWS IAM Auth Method's Access ID
as your gatewayAccessId
, and at least one other Access ID
in the allowedAccessPermissions
section to provide human users access to manage your Gateway:
globalConfig:
gatewayAuth:
gatewayAccessId: <Access ID>
gatewayAccessType: aws_iam
allowedAccessPermissions: {}
When working from an AWS instance with an IAM Role associated with it (which is the default state for EKS clusters that leverage the IAM Role of their Node group), nothing else is required - as the Gateway will be leveraging the IAM Role of the AWS instance itself where K8s is running.
Alternatively, you can also leverage an IAM Role assumed by a K8s Service Account in your Cluster. For that, you must either create an IAM Role bound to a K8s Service Account, or use an existing IAM role for annotating the Service Account in the Gateway's values.yaml
helm-chart:
Set the serviceAccountName
with the desired Kubernetes Service Account name, and set its eks.amazonaws.com/role-arn
annotation to the ARN of the IAM Role in question (which is constructed using the following format: arn:aws:iam::<AWS-Account-ID>:role/<IAM-Role-Name>
).
You can also create a new Service Account by simply setting the create
field to true
, so the serviceAccountName
you defined will be created upon deployment. Furthermore, if the serviceAccountName
is left empty, by default - the chart will create a new Service Account called <release name>-akeyless-gateway
.
Make sure to set the required role-arn annotation
to connect your IAM Role with the Service Account in any of the scenarios.
deployment:
annotations: {}
labels: {}
service_account:
create: true
serviceAccountName: <EKS SA name>
annotations:
eks.amazonaws.com/role-arn: arn:aws:iam::<AWS Account ID>:role/<IAM Role Name>
Save the file and proceed with the installation instructions.
GCP GCE
Google Kubernetes Engine (GKE) can run Akeyless Gateway in its secured and managed Kubernetes service in standard or autopilot mode.
Deploying Akeyless Gateway via the Helm chart using the authentication between your Gateway and Akeyless SaaS using our GCP Authentication method can be done using the GCP Workload Identity mechanism.
Workload Identity allows workloads in your GKE clusters to impersonate Identity and Access Management (IAM) Service Accounts to access Google Cloud services. Workload Identity is enabled by default on Autopilot clusters.
Follow the GKE workload identities guide to enable GKE workload identities on your cluster.
Create a Kubernetes service account for Akeyless Gateway to use. You can also use the default Kubernetes service account in the default or any existing namespace.
Use the existing IAM service account as provided in your GCP GCE auth method.
Note
When authenticating from a pod inside a Google Kubernetes Engine (GKE) cluster using GKE Workload Identity enabled, any
bounded rules
other thanBound Service Accounts
will not apply. GKE Workload Identity conceals metadata information about the running instance.To work with the GKE Workload Identity you must configure only the
Bound Service Accounts
field in your GCP Auth Method.
Allow the Kubernetes service account to impersonate the IAM service account by adding an IAM policy binding between the two service accounts. This binding allows the Kubernetes service account to act as the IAM service account.
Replace the following:
PROJECT_ID
: your Google Cloud project ID.
GSA_NAME
: the name of your IAM service account.
GSA_PROJECT
: the project ID of the Google Cloud project of your IAM service account.
KSA_NAME
: the name of your new Kubernetes service account.
NAMESPACE
: the name of the Kubernetes namespace for the service account.
gcloud iam service-accounts add-iam-policy-binding GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com \
--role roles/iam.workloadIdentityUser \
--member "serviceAccount:PROJECT_ID.svc.id.goog[NAMESPACE/KSA_NAME]"
Annotate the Kubernetes service account with the email address of the IAM service account.
kubectl annotate serviceaccount KSA_NAME \
--namespace NAMESPACE \
iam.gke.io/gcp-service-account=GSA_NAME@GSA_PROJECT.iam.gserviceaccount.com
Set the relevant K8s serviceAccountName
or leave it empty to use the default
K8s Service Account, update the annotations
, and enable the nodeSelector
to schedule the workloads on nodes that use Workload Identity and to use the annotated Kubernetes service account.
And set your GCP GCE Access ID
as your gatewayAccessId
and at least one another Access ID
in the allowedAccessPermissions
section, to provide human users access to manage your Gateway :
globalConfig:
gatewayAuth:
gatewayAccessId: <Access ID>
gatewayAccessType: gcp_gce
allowedAccessPermissions: {}
deployment:
annotations: {}
labels: {}
service_account:
create: false
serviceAccountName: <GKE SA Name>
annotations:
iam.gke.io/gcp-service-account: <GCP SA Name>
nodeSelector:
iam.gke.io/gke-metadata-server-enabled: "true"
Info
NodeSelector - For Autopilot clusters, omit the
nodeSelector
field. Autopilot rejects thisnodeSelector
because all nodes use Workload Identity.
Save the file and proceed with the installation instructions.
Azure Active Directory
Azure AD authentication is provided to AKS clusters with OpenID Connect. OpenID Connect is an identity layer built on top of the OAuth 2.0 protocol. Akeyless treats Azure as a trusted third party and verifies entities based on a JWT signed by the Azure Active Directory for the configured tenant.
To use Azure workload identity for your Gateway deployment, add the following label: azure.workload.identity/use: "true"
, set the AKS Service Account name and the Azure Client ID using the annotation azure.workload.identity/client-id
, and set your Azure Active Directory Access ID
as your gatewayAccessId
and at least one another Access ID
in the allowedAccessPermissions
section, to provide human users access to manage your Gateway:
globalConfig:
gatewayAuth:
gatewayAccessId: <Access ID>
gatewayAccessType: azure_ad
allowedAccessPermissions: {}
deployment:
annotations: {}
labels:
azure.workload.identity/use: "true"
service_account:
create: false
serviceAccountName: <AKS SA Name>
annotations:
azure.workload.identity/client-id: <user assigned client id>
Save the file and proceed with the installation instructions.
Universal Identity
Akeyless support Universal Identity authentication method for on-premise K8s cluster environments, eliminating the secret zero problems within your config files.
Universal Identity Authentication Method requires a dedicated K8s Secret to store the UID-Token
where the key of the secret has to be gateway-uid-init-token
.
Run the following command to store the K8s secret that stores the UID-Token
:
kubectl create secret generic uid-token \
--from-literal=gateway-uid-token=<base64-encoded-UID-Token>
Set your Universal Identity Access ID
as your gatewayAccessId
and at least one another Access ID
in the allowedAccessPermissions
section, to provide human users access to manage your Gateway, and set the K8s Secret name under gatewayCredentialsExistingSecret
:
globalConfig:
gatewayAuth:
gatewayAccessId: <Access ID>
gatewayAccessType: uid
allowedAccessPermissions: {}
gatewayCredentialsExistingSecret: uid-token
Save the file and proceed with the installation instructions.
Certificates
Certificate Authentication Method requires a dedicated K8s Secret to store the certificate.pem
and the corresponding private_key.pem
files, where the key of the secret has to be gateway-certificate
for the certificate
and gateway-certificate-key
for the private_key
:
kubectl create secret generic certificate-auth \
--from-literal=gateway-certificate=<base64-encoded-certificatem> \
--from-literal=gateway-certificate-key=<base64-encoded-private_key>
Set your Certificate Access ID
as your gatewayAccessId
, and at least one other Access ID
defined the allowedAccessPermissions
to provide human users access to manage your Gateway:
globalConfig:
gatewayAuth:
gatewayAccessId: <Access ID>
gatewayAccessType: certificate
gatewayCredentialsExistingSecret: certificate-auth
allowedAccessPermissions: {}
Save the file and proceed with the installation instructions.
Gateway Admins
To support local management of your Gateway configuration, you can set a list of Access ID
that will be able to log in and manage your Gateway. This setting can also work with Sub-Claims (when a shared authentication method is used), where for each entry you need to define a unique name
which should describe the Access Permission object, with an access-id
, sub_claims
when applicable, and a list of permissions
.
For example:
allowedAccessPermissions:
- name: Administrators
access_id: p-yyyyyy
sub_claims:
email:
- [email protected]
- [email protected]
group:
- Devops
permissions:
- admin
In this case, the above will create an Access Permission object named Administrators, associated with an Auth method p-yyyyyy
which for example is your SAML or OIDC Access ID
, where a user that at least matches one Sub-Claims attribute, will be authorized to access the Gateway with Admin permissions:
In our example, [email protected]
and test02@testhost
will be authorized, and any member of group=Devops
will also be authorized.
In this case, the Access ID
belongs to the authentication method created for the certain Identity Provider.
If you don't specify the sub-claims, every user authenticated by this IdP will be able to log in to the Gateway with admin privileges.
To work with API Key as an allowedAccessPermissions
simply provide your API Key Access ID
with a name
for the Access Permission object, with a set of permissions
.
Access Permissions
To delegate the exact permissions users will have on your Gateway components you can explicitly grant permissions, for example, to grant permissions to a user to manage only your Gateway Log Forwarding settings:
allowedAccessPermissions:
- name: Administrators
access_id: p-yyyyyy
sub_claims:
email:
- [email protected]
- [email protected]
group:
- Devops
permissions:
- admin
- name: LogForwarding
access_id: p-xxxxxx
sub_claims:
email:
- [email protected]
permissions:
- log_forwarding
In the above example, your Gateway Admins are [email protected],[email protected]
or any user which is part of your Devops
group in your IdP, where [email protected]
have permission to manage only your Gateway Log Forwarding settings.
Alternatively, you can use a Kubernetes Secret to delegate user permissions over the gateway.
First, define the access permissions as a JSON structure:
[
{
"name": "Administrators",
"access_id": <Access_ID>,
"sub_claims": {
"email": ["[email protected]"],
"group": ["DevOps"]
},
"permissions": ["admin"]
}
]
Then, encode the JSON structure in Base64 and create a Kubernetes secret:
kubectl create secret generic allowed-permissions \
--from-literal=allowed-access-permissions=<base64-encoded-json>
Set the name of the secret allowed-permissions
under allowedAccessPermissionsExistingSecret
where the key has to be allowed-access-permissions
.
Full list of available permissions:
Permission | Description |
---|---|
admin | Admin permission can manage all Gateway components, including Access Permissions |
defaults | Management of the defaults settings of your Gateway Including GatewayUrl ,TLS ,Default Encryption Key & Default AccessID for login. |
classic_keys | Management of Classic Keys |
dynamic_secret | Management of Dynamic Secrets |
rotated_secret | Management of Rotated Secrets |
targets | Management of all Targets items that were created using your Gateway |
automatic_migration | Management of Dynamic Secrets settings |
log_forwarding | Management of Log Forwarding settings |
zero_knowledge_encryption | Management of Zero-Knowledge |
caching | Management of Gateway Cache settings |
event_forwarding | Management of Event Forwarding settings |
ladp_auth | Management of LDAP Auth Gateway configuration. |
k8s_auth | Management of Kubernetes Auth Gateway configuration |
kmip | Management of KMIP Servers |
Note
Only Gateway Admins can delegate permissions to additional users. Any pre-provisioned settings will not be editable from the Akeyless Console.
You may also edit this parameter on your console, by going to the Gateways tab and selecting the desired Gateway. On the right of the screen, you will see the Gateway details, including Access Permissions.
CBA
To work with CBA flow for your Gateway-allowed users, In addition to the list of allowedAccessPermissions
you provided, set your chart with the enableSniProxy: true
setting under the TLSConf
section as follow:
TLSConf:
enableSniProxy: true
Note
All changes to allowed access IDs, such as editing, removing, and so on, can only be performed on post-deployment allowed access IDs. If an ID was defined during deployment it can't be removed or changed.
Installation
- To install the Gateway using the edited
values.yaml
file, run the following command:
helm install gw akeyless/akeyless-gateway -f values.yaml
- Check if the pods are up and running:
kubectl get pod
NAME READY STATUS RESTARTS AGE
gw-akeyless-gateway-6554f7c66c-56fgs 1/1 Running 0 5s
gw-akeyless-gateway-6554f7c66c-7jt8r 1/1 Running 0 5s
- Log in to the Gateway using your browser: http://Your-Akeyless-Gateway-URL:8000 - with your Gateway admin credentials.
Upgrade Gateway
To upgrade your Gateway, when working with a specific version, first edit the version in your values.yaml
file for example:
version: x.y.z
Update the helm repo and upgrade the helm deployment.
helm repo update
helm upgrade gw akeyless/akeyless-gateway -f values.yaml
Check that the new pods are starting.
Updated 10 days ago