Gateway Best Practices

This page provides recommended practices for the Akeyless Gateway across cloud and on-premises platforms.

Recommended deployment path

Use this path for production deployments:

1. Prepare a trusted, dedicated runtime environment.
2. Create the Gateway authentication method and associated access role before deployment.
3. Deploy Gateway using the method that matches your platform.
4. Configure cluster naming, encryption, administrators, and observability before go-live.
5. Use explicit image or package versions mapped to GA releases, and validate upgrades in lower environments.

Deployment model selection

Choose one deployment model based on your platform and operating model:

• Kubernetes with Helm: Gateway on Kubernetes
• Docker deployment: Install and Configure the Gateway
• Docker Compose deployment: Gateway with Docker Compose
• Serverless deployment: Serverless Gateway
• Azure Container Apps: Gateway on Azure Container Apps

Environment and network requirements

• Deploy Gateway in a trusted, dedicated environment. A dedicated runtime reduces lateral movement risk from unrelated workloads.
• Restrict and audit access to the hosting environment, orchestration platform, and deployment pipelines.
• Allow outbound HTTPS (443) from Gateway to the required Akeyless SaaS endpoints, as documented in Akeyless SaaS core service connectivity, US SaaS Core Services, and EU SaaS Core Services.
• Expose inbound ports according to the selected deployment model. For most Gateway deployments, 8000 is used for internal client access, but exact ingress requirements can differ by runtime and feature set.
• Validate deployment-specific inbound port requirements in:
  • Gateway on Kubernetes
  • Install and Configure the Gateway
  • Gateway with Docker Compose
  • Gateway on Azure Container Apps
• Configure TLS at the ingress or load balancer layer at minimum. End-to-end TLS is recommended for strict environments.
• Plan for additional egress requirements when connecting Gateway to private targets and integrations, including dynamic secrets, rotated secrets, Secure Remote Access (SRA), and certificate workflows.
• Additional ports can be required in future deployments based on runtime features and target integration patterns.

Image and versioning guidance

• If direct pulls from external repositories are restricted, use the Gateway image from Docker Hub: akeyless/gateway.
• Use explicit image or package versions that match GA releases published in the Akeyless changelog.
• The Gateway container image is compatible with non-root runtime policies, including OpenShift-style controls.
• Validate effective runtime user and group settings in your deployment policy. In Kubernetes, explicitly set runAsNonRoot, runAsUser, runAsGroup, and fsGroup according to your platform requirements.

Platform-specific operational guidance

Apply these controls according to the selected platform:

• Kubernetes:
  • Set minimum resource requests of 1 vCPU and 2Gi memory per pod.
  • Enable Horizontal Pod Autoscaler (HPA) and ensure Kubernetes Metrics Server is installed.
  • Manage chart values and lifecycle through GitOps workflows.
  • Set resource requests and limits for predictable scheduling and protection from noisy-neighbor workloads.
  • Use PodDisruptionBudgets to reduce downtime during voluntary disruptions.
  • Distribute pods with pod anti-affinity and topology spread constraints for resilience.
  • Use network policies to restrict pod-to-pod traffic to required paths only.
  • Apply Kubernetes RBAC and service account least privilege for Gateway workloads and automation.
• Virtual machines or bare metal:
  • Use host hardening baselines and restrict local administrative access.
  • Isolate Gateway runtime users and service credentials from other workloads.
• Serverless and managed containers:
  • Use workload identity where available instead of static long-lived secrets.
  • Enforce least-privilege egress and private networking controls.

Gateway application settings

• A Gateway cluster identity is defined by the combination of Gateway authentication method Access ID and clusterName.
• Changing either value creates a new logical Gateway cluster. Set a descriptive clusterName from day one.
• All instances in the same Gateway cluster are expected to share equivalent client-facing access and target-facing network reachability.
• Use a customer fragment for data fragment cryptography (DFC) and zero-knowledge workflows when required.
• Use HSM integration where hardware-backed key protection is required.
• Evaluate Gateway cache modes for continuity and latency requirements.
• Review advanced deployment options for your selected runtime before production rollout.

Caching strategy considerations

Caching is optional and should be enabled based on business continuity, performance, and risk requirements.

• Consider enabling Gateway caching to improve resilience during temporary SaaS connectivity interruptions and to reduce latency for repeated reads.
• Consider enabling proactive cache when read performance and reduced first-read latency are priorities.
• Consider cluster cache when running multiple Gateway instances that should share cache state.
• Evaluate security and operational tradeoffs before enabling caching:
  • Operational benefits: improved continuity, lower read latency, and reduced repeated upstream calls.
  • Operational costs: additional configuration, lifecycle management, monitoring, and capacity planning.
  • Security considerations: cache persistence policy, encryption controls, and data retention boundaries.
• Scope cache behavior to your environment and workload profile, then validate with telemetry and failure testing.

For implementation details and behavior, see:

• Configure the Gateway Cache
• QA on Gateway Caching

Gateway authentication method

Gateway requires an identity to communicate with the Akeyless identity security platform for non-interactive operations, such as secret rotation and revocation workflows.

ℹ️

Note:

Gateway runtime identity does not override end-user RBAC. End-user permissions are evaluated independently.

Cloud deployments

• For managed cloud platforms, prefer cloud-native IAM authentication.
• For Kubernetes deployments, follow the cloud IAM flow in Gateway on Kubernetes, including provider-specific workload identity setup.
• In managed Kubernetes services, implementation details can differ when workload identities are enabled or disabled.
• Configure workload identity integration according to platform-specific guidance.

On-premises deployments

For on-premises deployments, use one of the following methods:

• API key authentication:
  • Suitable for initial rollout and controlled environments.
  • Restrict client source networks with allowed IP ranges.
  • Set key expiry and automate rotation through operational workflows.
• Universal Identity:
  • Uses short-lived tokens and periodic rotation.
  • Configure TTL to balance resiliency and security.
  • Use a Redis-backed shared token flow across Gateway pods, with in-memory token handling for normal operation.
  • Keep token persistence enabled in each Gateway pod, and use persistent storage where possible to improve recovery after infrastructure failures.
  • If the token expires or is lost, restore the token and reset the Gateway identity flow. This can be automated.
  • Use persistent storage and automation to reduce manual recovery during infrastructure outages.
• Certificate-based authentication:
  • Store PEM certificate and private key in platform secrets storage.
  • Register the root certificate authority (CA) in the corresponding certificate auth method.
  • Use certificate claims to strengthen RBAC, and monitor certificate expiration and renewal.

Gateway access role

• Associate the Gateway authentication method with a dedicated access role that grants least privilege.
• For audit forwarding use cases, configure audit permissions explicitly with the required scope (own or all).
• For centralized SIEM forwarding, set Audit Log permission to all on one dedicated log-forwarding Gateway deployment.
• For Universal Secrets Connector (USC):
  • Grant read access to the target used by USC.
  • If secret sync is enabled, grant read and list permissions to the relevant secret paths.

Permission baseline by use case

Use this matrix as a working baseline for permission planning. Keep scopes limited to required paths and targets per environment.

Current guidance snapshots:

• Core Gateway identity:
  • Baseline permissions required for the deployed Gateway capabilities only.
  • Reference: RBAC
• Audit forwarding Gateway:
  • Option 1: Use one dedicated forwarding Gateway with Audit Log permission scope all.
  • Option 2: Use multiple forwarding Gateways with scoped Audit Log permissions, where scopes are mutually exclusive.
  • References: Log forwarding configuration, Audit Logs
• USC-enabled Gateway:
  • read on the USC target and read or list on synced secret paths.
  • Reference: Universal Secret Connector
• Gateway administrative users:
  • Assign only required Gateway access permissions per admin group.
  • Reference: Gateway access permissions

Gateway administrators

• Define a controlled list of human Access IDs (for example, SAML or OIDC) that can administer Gateway configuration.
• Configure administrator sub-claims and only the Gateway access permissions required for each admin group.
• Use separate admin groups for operations, security, and read-only review when possible.
• Review the permissions matrix in Gateway access permissions.

Resource planning for Kubernetes proactive cache

These recommendations apply to Kubernetes deployments where Gateway proactive cache is enabled.

ℹ️

Note (Scope):

The sizing guidance in this section is focused on secret retrieval, caching, and delivery workloads. Large-scale encryption and decryption workloads require separate capacity planning with higher CPU allocation.

For baseline Kubernetes controls, see Platform-specific operational guidance.

Cache architecture and behavior

• Cluster cache allows Gateway pods to share cached data through Redis.
• Proactive cache pre-fetches and refreshes eligible secrets to reduce read latency.
• Startup and refresh behavior can temporarily increase CPU and memory consumption during warm-up windows.
• For detailed cache behavior and failure modes, see QA on Gateway Caching.

Kubernetes cache-related configuration

The following settings have direct resource impact in proactive cache environments:

• PREFER_CLUSTER_CACHE_FIRST: Prioritizes cluster cache over local in-memory cache.
• CACHE_MAX_ITEMS: Controls maximum number of proactive cache items in Gateway in-memory cache.
• IGNORE_REDIS_HEALTH: Keeps /health returning 200 OK even when Redis is unavailable.

Baseline sizing guidelines by item count

The following baselines were collected from real Kubernetes environments and should be used as a starting point. Adjust based on observed traffic, item size distribution, and growth rate.

Applicable baseline: Gateway 4.46.0 and later.

How to use the sizing baselines

Use the tables as directional capacity-planning input, not as guaranteed performance targets.

• Treat each row as an initial sizing profile, then validate in your own environment.
• Size for steady-state plus burst behavior, cache warm-up, and maintenance windows.
• Recalculate limits and replica count as item count and request rate grow.
• Validate with load testing before production rollout and after major configuration changes.

Gateway pod sizing

ℹ️

Note:

The values below are reference baselines, not SLA commitments. Workload shape, secret size distribution, and integration mix can change resource requirements.

Cache pod sizing

ℹ️

Note:

Cache pod sizing depends on cached item characteristics, auth and RBAC matrix size, and active client footprint. Validate with runtime telemetry.

Operational recommendations

• Run at least 2 Gateway pods for availability. For most production environments with proactive cache, 3-4 pods is a practical baseline.
• Keep memory and CPU headroom above observed peaks to absorb cache warm-up, burst traffic, and maintenance operations.
• A practical starting buffer is 125%-150% of observed peak utilization.
• Set alerts before hard limits are reached:
  • 70% utilization: trend review and scaling plan.
  • 80% utilization: alert and capacity action window.
  • 90% utilization: immediate resource or replica increase.

Key metrics to monitor for resource planning

In addition to the observability metrics listed below, monitor:

• Memory utilization against limits for Gateway and cache pods.
• OOMKill events and restart rates.
• CPU usage and throttling rates.
• Gateway request rates, response latency, and error trends.
• Cache growth trends correlated with item count growth.

For full monitoring guidance and alerting context, see Gateway observability.

For telemetry implementation details and metric export options, see:

• Telemetry metrics on Kubernetes
• Telemetry metrics

Gateway observability

• Monitor Gateway and host or cluster health continuously.
• Consume Gateway metrics using Kubernetes telemetry metrics and Telemetry metrics for non-Kubernetes deployments.
• Prioritize baseline platform metrics documented in telemetry pages:
  • akeyless.gw.system.cpu.*
  • akeyless.gw.system.memory.*
  • akeyless.gw.system.load.*
  • akeyless.gw.system.disk.*
  • akeyless.gw.system.network.*
  • akeyless.gw.system.saas.connection_status
  • akeyless.gw.system.healthcheck.status
• Track connectivity and cache resilience behavior:
  • Alert on SaaS connectivity degradation (akeyless.gw.system.saas.connection_status).
  • Monitor cache continuity and offline-mode behavior as documented in Configure the Gateway Cache.
• Monitor Gateway logs and forwarding health:
  • Collect standard output logs through the platform logging pipeline.
  • Configure Log forwarding configuration and Audit Logs forwarding to your SIEM.
  • For larger environments, use either one dedicated Gateway with all audit scope, or multiple Gateways with mutually exclusive scoped audit permissions.
• Monitor control-plane and automation signals surfaced by Gateway runtime behavior:
  • Leader-only workflows: log forwarding runs only on the log-forwarding leader, and periodic security-health updates run only on the rotator leader.
  • Universal Secrets Connector (USC) sync status: alert on repeated sync failures and persistent USC last error updates.
  • Cache and Redis health: alert on repeated cache key provisioning failures and Redis-health-related state changes.
• Add account-level monitoring and alerting by integrating Event Center notifications for failures, expirations, and operational drift.

Industry-aligned security practices

In addition to Akeyless-specific settings, align deployment policy with common security standards:

• Enforce pod hardening and non-root controls for Kubernetes workloads using Kubernetes Pod Security Standards.
• Apply guidance from the Cybersecurity and Infrastructure Security Agency (CISA) for Kubernetes and cloud-native hardening.
• Configure TLS policy and certificate operations using OWASP Transport Layer Protection guidance.