Self-Host Akamai App Platform on Kubernetes

What Akamai App Platform provides

Akamai App Platform is a pre-built Kubernetes developer platform intended to help teams deploy, manage, observe, expose, and secure containerized workloads. The open-source implementation is maintained in the linode/apl-core repository under the Apache 2.0 license. It is optimized for Linode Kubernetes Engine, but Akamai also documents a custom installation path for other conformant Kubernetes services.

App Platform is not one independent web application or a single pod. It coordinates multiple Kubernetes controllers, operators, databases, ingress resources, identity services, and developer tools. Configuration-as-code and GitOps workflows manage desired state, while the browser-based portal gives developers a central interface for workloads, application templates, images, secrets, repositories, networking, logs, metrics, and related platform capabilities.

Platform administrators receive a multi-tenant foundation for onboarding teams, managing users, applying policies, and operating shared capabilities. Developers can build OCI-compliant images from source, deploy workloads through GitOps, expose applications, manage secrets, access telemetry, and work with private repositories and CI/CD pipelines when the corresponding applications are enabled.

Use the Apps documentation as the current inventory

The repository README and the current App Platform Apps documentation do not categorize every component in the same way. The README describes a broader group of core integrations, while the Apps page distinguishes applications that are always installed from applications that can be activated optionally. For deployment planning, use the release-matched Apps documentation and chart values rather than treating the README categories as an immutable installation manifest.

Release status also matters. The v6.3.0 release notes mark Kubeflow Pipelines as deprecated and introduce an add-ons capability for platform administrators to deploy custom Argo CD applications. Review the v6.3.0 release notes or the notes for the version you actually install before depending on an optional component.

Choose the correct installation path

App Platform has three documented installation paths. Select the path before sizing the cluster or writing values because the requirements are not identical.

Resolve the conflicting LKE sizing statements conservatively

Two current Akamai pages describe LKE resources differently. The Cloud Manager getting-started page says App Platform requires at least three workers with a combined minimum of 16 GB memory and 12 CPUs. The Akamai App Platform product page says at least three workers, each with at least 16 GB memory and 4 vCPUs. Those statements should not be merged into an unofficial fourth requirement.

For a new LKE deployment, the conservative interpretation is three workers with at least 16 GB memory and 4 vCPUs each, while also confirming what the current Cloud Manager interface enforces. If capacity or cost planning depends on the smaller total-memory statement, resolve the discrepancy with the current LKE documentation or Akamai support before provisioning.

Neither LKE statement changes the separate custom-provider prerequisite. The custom installation page currently specifies Kubernetes 1.33 or newer and a node pool with at least 6 vCPU and 12 GB RAM. These are minimums, not production sizing recommendations. Optional applications, builds, user workloads, telemetry retention, databases, and availability goals can require substantially more allocatable capacity.

Prerequisites for the custom installation

A successful helm install submission does not prove that App Platform will become usable. Controllers may remain blocked by missing storage, insufficient scheduling capacity, an unavailable external IP, unsupported networking, DNS failures, or duplicate cluster services. Validate the underlying cluster first.

Begin with read-only checks:

kubectl config current-context
kubectl cluster-info
kubectl get nodes -o wide
kubectl get storageclass
helm version
kubectl version

Confirm that every intended worker reports Ready. Compare the server version, not only the local kubectl client version, with the platform requirement. In the StorageClass output, identify whether one suitable class is marked as the default.

Prepare storage, load balancing, networking, and DNS

Configure the default StorageClass

The custom installation uses the cluster's default StorageClass unless an application receives another class through its raw values. If a suitable class exists but is not currently the default, the documented command is:

kubectl patch storageclass <your-storage-class> -p '{"metadata": {"annotations":{"storageclass.kubernetes.io/is-default-class":"true"}}}'

Replace the placeholder with the exact name returned by kubectl get storageclass. Before changing the default, review the class's performance, expansion, reclaim, failure-domain, and topology behavior. The change can affect every workload that creates a PersistentVolumeClaim without explicitly naming a class.

App Platform also supports selecting a StorageClass per application through _rawValues. The documented Harbor example is:

app:
  harbor:
    _rawValues:
      persistence:
        persistentVolumeClaim:
          registry:
            storageClass: <your-storage-class>
            size: 5Gi

This structure applies to the shown Harbor configuration. Do not assume that another integrated application uses the same value hierarchy. Check the schema for the App Platform release and application being customized.

Provide an address for the LoadBalancer Service

App Platform creates a Kubernetes Service of type LoadBalancer. Managed Kubernetes providers commonly supply an implementation for this service type. Bare-metal and on-premises clusters often do not, which leaves the external address in Pending.

The custom installation documentation suggests MetalLB for on-premises environments:

kubectl create namespace mlb
helm repo add metallb https://metallb.github.io/metallb
helm repo update
helm install metallb metallb/metallb -n mlb
sleep 60

cat <<EOF | kubectl apply -f -
apiVersion: metallb.io/v1beta1
kind: IPAddressPool
metadata:
  name: default-pool
  namespace: mlb
spec:
  addresses:
  - <start-ip>-<end-ip>
---
apiVersion: metallb.io/v1beta1
kind: L2Advertisement
metadata:
  name: default-pool
  namespace: mlb
EOF

Use an address range reserved for load-balancer allocation. Do not select arbitrary DHCP addresses or addresses already assigned to other systems. L2 adjacency, routing, address ownership, and firewall behavior depend on the network design.

If the provider requires annotations on the NGINX ingress LoadBalancer Service, the documentation shows this provider-specific example:

ingress:
  platformClass:
    entrypoint: ''
    annotations:
      - key: service.beta.kubernetes.io/do-loadbalancer-enable-proxy-protocol
        value: true

This is not a universal setting. Apply only annotations documented by the infrastructure provider. An incorrect proxy-protocol setting can prevent ordinary HTTP traffic from being parsed correctly.

Use a Kubernetes 1.33-compatible CNI

NetworkPolicy resources are effective only when the active CNI enforces them. First identify the CNI installed by the cluster provider. Do not install a second CNI or replace the current implementation simply because the App Platform custom-installation page mentions Calico.

The current custom-installation page still shows Calico 3.26.3 commands. That Calico release predates the stated Kubernetes 1.33 minimum, and the supplied current documentation does not establish that 3.26.3 is compatible with Kubernetes 1.33 or newer. For that reason, this guide does not present those pinned commands as safe, runnable instructions.

Handle Metrics Server correctly

App Platform installs Metrics Server by default. If the cluster provider already operates it, disable the platform-managed copy:

apps:
  metrics-server:
    enabled: false

For clusters whose kubelet endpoints use certificates that Metrics Server does not trust, the documented setting is:

apps:
  metrics-server:
    extraArgs:
      - --kubelet-insecure-tls=true

This relaxes certificate validation between Metrics Server and kubelets. Use it only when required by the cluster's certificate configuration. A properly trusted certificate chain is preferable.

Prepare DNS and autoscaling

The custom provider requires access to a DNS zone. Its installation example uses a Linode DNS API token, but the provider can be used with other DNS services. Do not transplant the Linode provider block into another DNS environment. Obtain the exact provider schema supported by the App Platform release you are installing.

App Platform does not install Cluster Autoscaler. If worker autoscaling is required, install the implementation supported by your Kubernetes provider. Identity permissions, node-group discovery, and scaling constraints are provider-specific, so there is no safe universal command.

Install apl-core with Helm

The official custom installation page defines three Helm steps: create the values file, add and update the chart repository, and install the chart. Review the values before resources are created.

Step 1: Create values.yaml

The documented Linode DNS example is:

tee values.yaml<<EOF
cluster:
  name: $CLUSTER_NAME
provider: custom

# optionally configure metrics-server for kubelet-insecure-tls
apps:
  metrics-server:
    extraArgs: ["--kubelet-insecure-tls=true"]

# dns is required!
dns:
  domainFilters:
    - <your-domain>
  provider:
    linode:
      apiToken: $LINODE_TOKEN
EOF

Set CLUSTER_NAME and, for this specific example, LINODE_TOKEN before running the command. Replace <your-domain> with the zone intended for App Platform. The unquoted heredoc expands shell variables into the file, so confirm they are populated without printing the resulting token into shared logs.

Remove the insecure kubelet TLS override when it is not required. If the provider already runs Metrics Server, replace that section with enabled: false. For another DNS provider, use its current App Platform schema rather than guessing field names.

Step 2: Add the chart repository

helm repo add apl https://linode.github.io/apl-core
helm repo update

If the repository name already exists, verify its configured URL:

helm repo list

Step 3: Install the release

helm install -f values.yaml apl apl/apl

This creates a release named apl. A successful command means Kubernetes accepted the release resources. It does not prove that the operator completed its first apply, that dependent applications are ready, or that the portal can complete an authentication flow.

Complete the release-matched post-installation workflow

Akamai's getting-started sequence explicitly places post-installation after chart installation. Do not expose the platform or begin onboarding developers until this phase is complete.

1. Record the installed release and rendered configuration

helm list -A
helm status apl
helm get values apl -a
helm get manifest apl > apl-rendered-manifest.yaml

Run the release commands in the release namespace if Helm reports one other than the current namespace. Store exported material in a protected administrative location. Review it before retention because rendered manifests and computed values can contain sensitive configuration.

2. Check workloads, events, and operator progress

kubectl get pods -A
kubectl get deployments,statefulsets,daemonsets -A
kubectl get jobs -A
kubectl get events -A --sort-by=.lastTimestamp

Investigate pods that remain Pending, restart repeatedly, fail readiness checks, or report image, mount, permission, or scheduling errors. In v6.3.0, operator readiness is designed to signal completion of the first successful apply. For another release, use its release notes to interpret readiness behavior.

3. Verify persistent storage

kubectl get pvc -A
kubectl get pv

Expected claims should become Bound. A pending claim commonly indicates a missing default StorageClass, failed dynamic provisioning, unsupported access behavior, topology constraints, or an app-specific class that does not exist.

4. Discover the installed ingress endpoints

Do not guess the console service, namespace, hostname, or port. List the actual ingress rules generated by the installed release:

kubectl get svc -A
kubectl get ingress -A
kubectl get ingress -A -o custom-columns='NAMESPACE:.metadata.namespace,NAME:.metadata.name,CLASS:.spec.ingressClassName,HOSTS:.spec.rules[*].host,ADDRESS:.status.loadBalancer.ingress[*].ip'

If the provider returns a hostname rather than an IP address, the abbreviated custom-column output may not show it. Use the full ingress description:

kubectl describe ingress -n <namespace> <ingress-name>

Identify the portal or console ingress by its resource name, routes, and backend, then record its exact configured host. That hostname is the canonical browser entry point for the deployment. Verify that its DNS record resolves to the ingress address and that the certificate presented for HTTPS covers the same hostname.

5. Retrieve the initial credentials using the installed release's instructions

Initial credential storage is release-sensitive. Secret names, namespaces, and keys must not be guessed. First inspect the notes packaged with the installed chart:

helm get notes apl

Follow the credential retrieval instruction in those notes and the post-installation page corresponding to the chart version recorded earlier. If the instruction retrieves a Kubernetes Secret, run it only from an authorized administrative terminal. Do not copy the decoded value into shell history, chat, issue trackers, or shared logs.

If the installed chart does not provide credential retrieval instructions in its notes, stop rather than searching and decoding arbitrary cluster Secrets. Use the post-installation instructions linked by the official App Platform getting-started guide for that release. This safeguard prevents an administrator from confusing a database, service-account, OAuth client, or Keycloak internal credential with the platform login.

6. Complete the first login through the canonical hostname

Open the exact HTTPS hostname found in the ingress resource. Confirm that the certificate and browser address refer to that hostname. Sign in with the documented initial account, complete any password-change or account-initialization prompt presented by the installed release, and sign out and back in to verify that the resulting credentials work.

Do not substitute a load-balancer IP, an arbitrary localhost URL, or an alternate public tunnel hostname for this test. Keycloak and OIDC flows depend on issuer URLs, browser redirects, callback URLs, secure cookies, and hostname-aware ingress routing. Testing first through the configured canonical host separates platform readiness from proxy compatibility.

7. Complete required administrative configuration

Before onboarding developers, review platform users, administrative membership, team or tenant configuration, DNS behavior, enabled applications, and identity-provider settings exposed by the installed release. Remove unnecessary privileged access and avoid enabling optional applications until their release stage, resources, storage, and recovery requirements have been reviewed.

If external identity is configured, verify that the issuer, authorization endpoint, token endpoint, redirect URIs, and logout redirect behavior all use the intended canonical public origin. An OIDC login that starts successfully but returns to another hostname is not ready.

8. Perform readiness checks from a user perspective

• The Helm release exists and its recorded chart version matches the post-installation instructions being followed.
• Required deployments, stateful workloads, daemon sets, jobs, and operators are healthy.
• Required PersistentVolumeClaims are bound.
• The LoadBalancer has a usable address and ingress rules contain the intended hostnames.
• DNS resolves those hostnames to the intended ingress path.
• HTTPS presents a certificate valid for the canonical hostname.
• The first login completes without a redirect loop or callback error.
• A platform administrator can reach the expected portal and application-management views.
• Enabled applications report the expected lifecycle state for the installed release.
• Bootstrap credentials and DNS provider credentials are handled according to the organization's credential policy.

The platform is demonstrably usable only after these infrastructure and user-facing checks succeed. Pod readiness alone is insufficient.

Operate, upgrade, recover, and remove the platform safely

App Platform coordinates many independently stateful and versioned applications. Treat upgrades, rollback, backup, identity changes, and removal as planned platform changes rather than generic one-command Helm tasks.

Respect application release stages

The criteria documented by Akamai cover backup and restore, database upgrades, lifecycle management, authentication and authorization, graceful termination, continuity, Kubernetes-version support, monitoring, and resource management. A release-stage label therefore has direct operational significance.

Prepare an upgrade

1. Record the current chart version, effective Helm values, application inventory, Kubernetes version, ingress hosts, and storage configuration.
2. Read every intermediate release note between the installed and target versions. Check application updates, deprecations, required value changes, and Kubernetes compatibility.
3. Back up platform data, configuration, identity information, databases, and external dependencies according to the recovery objectives for your environment.
4. Verify that backups can be restored in a non-production recovery test.
5. Confirm that the target App Platform release supports the cluster's Kubernetes version and that enabled applications support the target release.
6. Schedule the change and define user-visible health checks for login, GitOps synchronization, builds, registry access, telemetry, and exposed applications.

Do not assume that helm upgrade alone is the complete procedure. The target release may include operator, schema, database, identity, and application changes. Use the upgrade instructions and release notes for the exact source and target versions.

Plan rollback before upgrading

A Helm revision rollback restores Kubernetes manifests, but it does not automatically reverse every database migration, persistent-volume change, external DNS update, credential rotation, or application-level schema change. A safe rollback plan must define which components can be rolled back through Helm, which require data restoration, and which are forward-only.

Preserve the previous chart version and sanitized values, but do not run helm rollback merely because a pod is unhealthy. First determine whether the release notes support rollback across the attempted version boundary. If they do not, restore through the release-specific recovery procedure.

Back up and restore the whole service, not only manifests

A complete recovery plan can include cluster configuration, App Platform values, application configuration, Keycloak identity data, databases, Git repositories, registry content, object storage, persistent volumes, DNS state, certificates, and external secrets. The exact set depends on the applications enabled in your release.

Kubernetes manifests are not a substitute for stateful backups. Likewise, the presence of a backup job does not prove recoverability. Test restoration, record recovery time, and verify that authentication, GitOps reconciliation, workloads, and ingress still work after recovery.

Rotate credentials deliberately

Track bootstrap administrator credentials, DNS API tokens, external identity-provider secrets, registry credentials, database credentials, webhook secrets, and Localtonet device tokens as separate assets. Rotate them through the owning application's supported procedure. Updating a Kubernetes Secret directly may not cause a controller or application to reload it, and can break generated configuration.

After any identity or OIDC change, test login and logout through the canonical hostname. Verify redirect URIs, issuer discovery, token validation, and administrative access before ending the maintenance window.

Remove the platform only after preserving required data

A Helm uninstall can remove release-managed Kubernetes resources, but it may not remove persistent volumes, provider load balancers, DNS records, object-storage data, externally managed secrets, or applications created through separate GitOps flows. It can also trigger destructive deletion depending on resource ownership and reclaim policies.

Before removal, stop new platform changes, inventory retained data, export configuration, perform and test final backups, record DNS and identity settings, and identify resources managed outside the release. Use the uninstall procedure for the installed App Platform release. Afterward, audit namespaces, cluster-scoped resources, PersistentVolumes, load balancers, DNS records, cloud storage, and credentials rather than assuming Helm removed everything.

Use Localtonet only with a hostname-compatible endpoint

Localtonet can expose an HTTP service reachable from the device running our client. The client establishes an outbound connection to a Localtonet relay, so this access path does not require inbound router port forwarding, firewall changes, a VPN, or a public IP address.

App Platform introduces an important compatibility condition: its ingress and authentication stack are hostname-aware. A random Localtonet public hostname is not automatically equivalent to the hostname configured in App Platform. The ingress may reject or misroute an unexpected Host header, TLS may target another server name, and Keycloak or another OIDC provider may redirect the browser back to the canonical platform origin.

Validate the upstream from the client device

Run our client on a device that can already reach the intended ingress. Test the canonical host from that device before creating a tunnel. When the ingress address is private but DNS resolves elsewhere, a hostname-preserving test can distinguish basic reachability from virtual-host routing:

curl -I https://<canonical-platform-hostname>/

If you must test a specific ingress address while preserving the hostname, use an HTTP client feature that maps the hostname to that address for the test. Do not disable certificate validation as the normal solution. Confirm that the response is the intended portal or authentication redirect, not an ingress default page.

Choose the Localtonet process type carefully

Localtonet HTTP tunnels can use Random Sub Domain, Custom Sub Domain where supported, or Custom Domain. All provide a public HTTPS address, but App Platform compatibility depends on the hostname seen by the browser and upstream.

Create the tunnel after compatibility is established

See our HTTP tunnel documentation for the current dashboard workflow. Check the current custom-domain requirements before making DNS changes.

Troubleshoot in dependency order

Troubleshoot from the lowest dependable layer upward: node health, CNI, storage, workloads, LoadBalancer, ingress, DNS, TLS, canonical-host login, local client reachability, and finally the Localtonet URL. This sequence prevents a public access symptom from hiding an underlying Kubernetes or identity failure.

Frequently asked questions