Self-Host Akamai App Platform on Kubernetes

What Akamai App Platform and apl-core provide

Akamai App Platform is a pre-built Kubernetes developer platform designed to help teams deploy, manage, expose, observe, 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 its documented custom provider supports installation on another conformant Kubernetes cluster.

This is not a single web application installed as one isolated pod. It is an integrated platform made from multiple Kubernetes projects and controllers. The platform uses Kubernetes Operators and GitOps principles to manage desired state through configuration. Its browser-based self-service experience gives developers a central place to work with application templates, workloads, images, secrets, repositories, networking, and operational data.

Platform administrators receive a multi-tenant foundation for onboarding development teams, applying governance, managing users, implementing network policies, and operating shared platform capabilities. Developers can build OCI-compliant images from source, deploy containerized workloads through GitOps, expose applications, access logs and metrics, create secrets, and use private Git repositories and CI/CD pipelines.

Choose the correct installation path

The project documents three installation paths. The correct choice depends on whether you are creating a new LKE cluster, adding the platform to an existing LKE cluster, or operating Kubernetes through another provider.

The automatic LKE path documents a node pool with at least three workers, at least 16 GB of total memory, and 12 total CPUs. It also requires an HA control plane. The custom-provider documentation gives a different minimum: Kubernetes 1.33 or higher and a node pool with at least 6 vCPU and 12 GB RAM. These requirements belong to different installation paths and should not be combined into a new, unofficial sizing formula.

Minimum resources are also not the same as production capacity. Workloads, optional platform applications, retention policies, build activity, database usage, and observability volume can increase resource requirements. Plan capacity around the applications and traffic that will actually run on the cluster.

Prerequisites for a custom Kubernetes installation

Before adding the Helm repository or creating the platform values file, confirm that the underlying cluster satisfies every dependency. A successful Helm submission does not prove that the platform will become operational. Controllers can remain pending when storage, load balancing, DNS, resources, or networking are incomplete.

Begin with read-only checks. These commands show the active cluster, node versions, node health, and available storage classes:

kubectl cluster-info
kubectl get nodes -o wide
kubectl get storageclass

Confirm that every intended worker reports Ready. In the StorageClass output, identify whether one class is marked as the default. Also confirm that your current Kubernetes context is the correct environment before running any installation command:

kubectl config current-context

Prepare storage, load balancing, networking, and DNS

Configure a default StorageClass

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

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

Replace <your-storage-class> with the exact StorageClass name returned by Kubernetes. Before changing the default, verify that the class has the performance, availability, expansion, reclaim, and topology behavior expected for this cluster. Changing the default affects other workloads that create PersistentVolumeClaims without naming a class.

The platform also supports selecting another StorageClass per application through _rawValues. The documented Harbor example is:

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

This example applies specifically to the shown Harbor value structure. Do not assume that every integrated application exposes the same nesting or storage fields. Use the schema and documentation for the application being customized.

Provide an external IP for the LoadBalancer Service

During installation, App Platform creates a Kubernetes Service of type LoadBalancer. The resulting external IP must be accessible from within the cluster. Managed cloud platforms commonly provide an implementation for this service type. Bare-metal and on-premises clusters often do not, which can leave the external address pending indefinitely.

The custom-installation documentation suggests MetalLB for on-premises environments. Its documented example is:

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

Replace the address placeholders with a range reserved for load-balancer allocation on your network. Do not select arbitrary DHCP addresses or addresses already assigned to other devices. The correct range, L2 reachability, and routing rules depend on your network design. Coordinate this change with the network administrator when the cluster is not an isolated lab.

App Platform installs an NGINX Ingress Controller. If the Kubernetes provider requires annotations on the LoadBalancer Service, add those annotations to the chart values. The documentation provides this example:

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

That annotation is provider-specific. It is an example, not a universal requirement. Use only the annotations documented by the infrastructure provider operating your load balancer.

Install a NetworkPolicy-capable CNI when needed

Network policies require enforcement by the cluster's CNI. The documentation identifies Calico or another CNI that supports Kubernetes NetworkPolicy. If your cluster already has a compatible CNI, do not layer another implementation on top without confirming that the combination is supported.

The documented Tigera Operator installation is:

helm repo add projectcalico https://docs.tigera.io/calico/charts
helm repo update
kubectl create namespace tigera-operator
helm install calico projectcalico/tigera-operator --version v3.26.3 --namespace tigera-operator

The documented minimal Calico alternative is:

kubectl apply -f https://raw.githubusercontent.com/projectcalico/calico/v3.26.3/manifests/calico.yaml

Handle Metrics Server correctly

App Platform installs Metrics Server by default. If the Kubernetes provider already includes it, disable the platform-managed copy in values.yaml:

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 for Metrics Server's kubelet connection. Use it only when required by the cluster's certificate configuration and after understanding the trust implications. A properly trusted certificate configuration is preferable where it is practical.

Prepare DNS and optional autoscaling

A DNS zone is required by the custom provider. The provider can be used with different DNS services, but the exact values and credentials depend on that service. The installation sample supplied by the project uses a Linode DNS token. Do not copy that provider block unchanged when using another DNS provider.

App Platform does not install Cluster Autoscaler. If dynamic worker scaling is required, install and configure the implementation supported by your infrastructure provider separately. The appropriate autoscaler command, identity permissions, and node-group configuration are provider-specific, so there is no safe universal command to include.

Install apl-core with Helm

Once the cluster prerequisites are satisfied, the custom installation itself has three documented Helm steps: create values.yaml, add and update the App Platform Helm repository, and install the chart. Keep this sequence intact so that configuration is reviewed before resources are created.

Step 1: Create values.yaml

The documented sample 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 Linode DNS example, LINODE_TOKEN in the current shell before running the command. Replace <your-domain> with the DNS zone intended for the platform. Because the heredoc is not quoted, shell variables are expanded into the resulting file. Inspect the file carefully without exposing its contents in shared logs or terminal recordings.

Remove the metrics-server insecure TLS override if the cluster does not require it. If the provider already operates Metrics Server, replace that section with the documented enabled: false setting. If you use a DNS service other than the one shown, obtain its exact supported provider schema from the current App Platform documentation. The evidence for this guide does not establish those provider-specific field names, so guessing them would risk a failed installation or leaked credentials.

Step 2: Add the Helm repository

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

If Helm reports that the repository name already exists, inspect the currently configured URL before deciding whether to reuse or replace it:

helm repo list

Step 3: Install the chart

helm install -f values.yaml apl apl/apl

This creates a Helm release named apl. The command submitting successfully means Kubernetes accepted the release resources. It does not by itself prove that every controller, database, ingress, certificate, identity component, and optional dependency is ready.

Verify the installation before using it

Verification should proceed from the Helm release to Kubernetes resources, storage, ingress, DNS, and finally the browser-based platform. Avoid debugging through the public hostname first. Lower-level status normally reveals whether the issue is scheduling, storage, networking, load balancing, DNS, certificates, or authentication.

Check the Helm release

helm status apl
helm list -A

Confirm that the release appears in Helm and note the namespace reported by helm status. Do not assume a namespace name that was not explicitly selected in your installation.

Inspect pods and recent events

kubectl get pods -A
kubectl get events -A --sort-by=.lastTimestamp

Look for pods that remain Pending, repeatedly restart, or report image, mount, scheduling, readiness, or permission errors. Events often explain conditions that a simple pod list cannot, including insufficient CPU or memory, unbound PersistentVolumeClaims, failed mounts, unavailable external addresses, and admission-policy failures.

App Platform includes many interconnected applications, so readiness may not be instantaneous. Persistent failures should be investigated rather than hidden by repeatedly reinstalling the release.

Verify persistent storage

kubectl get pvc -A
kubectl get pv

Claims expected by the platform should progress to Bound. A claim remaining Pending commonly indicates that no usable default StorageClass exists, dynamic provisioning is failing, topology constraints cannot be satisfied, or the requested storage settings are incompatible with the provider.

Verify the LoadBalancer and ingress resources

kubectl get svc -A
kubectl get ingress -A

Identify the service of type LoadBalancer and check whether an external address has been assigned. For an on-premises cluster, a persistent Pending address usually means there is no working load-balancer implementation or its address pool is invalid. Confirm that any assigned address is reachable from inside the cluster, as required by the custom installation.

Review the ingress hostnames generated from your DNS configuration. Then check the corresponding DNS records through your normal DNS tooling. DNS propagation alone cannot repair an incorrect zone, rejected API credentials, an inaccessible load-balancer address, or a failed certificate workflow.

Complete post-installation configuration

The project explicitly requires a post-installation phase. That phase may include locating the initial username and password and completing other setup. The supplied evidence does not establish the exact command, secret name, namespace, hostname, or credential retrieval procedure, so this guide does not invent one.

Use the post-installation instructions matching the exact App Platform release you installed. Before remote access, verify all of the following:

• The platform's documented console hostname resolves to the intended address.
• The browser can reach the console from an authorized network location.
• The expected login page appears rather than a generic ingress error.
• The documented administrator credential procedure succeeds.
• Default or bootstrap credentials are changed when the platform workflow permits or requires it.
• Only intended users and teams have platform access.

Operate the platform after installation

A successful installation is the beginning of platform operations, not the end. App Platform coordinates multiple applications with different responsibilities and release stages. Administrators should treat platform configuration, application activation, upgrades, backups, access controls, and capacity as controlled operational changes.

Understand included and optional applications

The current application documentation separates always-installed applications from optional ones. Always-installed applications include Argo CD, External Secrets Operator, Istio, Keycloak, OpenTelemetry, Prometheus, and Sealed Secrets Operator. Optional applications include Alertmanager, CloudNativePG, Gitea, Grafana, Harbor, Knative, Kserve, Kubeflow Pipelines, Kyverno, Loki, RabbitMQ, Tekton, Trivy, and Valkey.

Exact availability and lifecycle can change by App Platform release. For example, the supplied v6.3.0 release evidence marks Kubeflow Pipelines as deprecated and introduces an add-ons capability for platform administrators to deploy custom Argo CD applications. Review the release notes before enabling a component or planning a dependency around it.

The integration criteria cover backup and restore, database upgrades, lifecycle management, authentication and authorization, graceful termination, continuity, Kubernetes version support, monitoring, and resource management. A component's release stage therefore matters operationally, not just cosmetically.

Use the platform for application workflows

After administrators finish post-installation setup and onboard teams, developers can use quickstarts or organization-specific templates to build images and deploy workloads. Applications can be exposed publicly through the platform's Kubernetes and ingress-oriented workflow. Teams can also configure network policies, response headers, CNAMEs, secrets, logs, metrics, traces, and automated image updates where those capabilities are enabled.

Localtonet is not a replacement for those native application-delivery workflows. If an application is intended to be a durable public production service, use the platform's supported ingress, DNS, certificate, identity, policy, and observability design. Localtonet is most relevant when an administrator needs controlled remote reachability to a private HTTP endpoint, a temporary review environment, or a service that should not require inbound network changes.

Plan upgrades and backups

Do not assume that a generic helm upgrade command is the complete upgrade procedure. App Platform releases can update core applications, schemas, operators, and platform behavior. Review the release-specific upgrade instructions, deprecations, and compatibility information before changing versions.

Back up the data and configuration required by your recovery objectives before upgrades. Also test restoration rather than treating the existence of a backup as proof of recoverability. The platform documentation defines backup and restore as an application integration criterion, but each environment still needs an operational recovery plan for cluster infrastructure, DNS, credentials, configuration, persistent data, and external dependencies.

Access a private App Platform HTTP endpoint with Localtonet

Complete this section only after the platform endpoint works from the device or network where the Localtonet client will run. Localtonet exposes a reachable local HTTP service through an outbound connection to one of our relay servers. This means you do not need inbound router port forwarding, firewall changes, a VPN, or a public IP address for the Localtonet access path.

The client device must be able to reach the selected App Platform endpoint. Depending on your deployment, that endpoint might be an internal ingress address or another HTTP address established by your Kubernetes and post-installation configuration. The supplied App Platform evidence does not define a universal console address or port, so discover and verify the real endpoint before creating the tunnel.

Identify the correct HTTP target

From the machine that will run our client, open the App Platform endpoint or test it with an HTTP client. Verify that it returns the intended platform login or application response. Do not target the Kubernetes API server, a database, an identity backchannel, an administrative metrics port, or an arbitrary service discovered in the cluster.

If the endpoint is accessible only inside the Kubernetes network, choose an approved method to make it reachable from the Localtonet client device. The correct design depends on cluster networking. This guide does not provide a fabricated kubectl port-forward command because the required namespace, resource name, address, and port are installation-specific and are not established by the supplied evidence.

Create and start the Localtonet HTTP tunnel

For the current dashboard workflow, consult our Localtonet HTTP tunnel documentation. Custom-domain DNS requirements can change, so verify the current documentation before adding or modifying DNS records.

Troubleshoot installation and remote access

Work from the lowest dependable layer upward. First verify cluster health, then storage and scheduling, followed by the LoadBalancer, ingress, DNS, platform login, local HTTP reachability, and finally the Localtonet tunnel. This order prevents a public access symptom from obscuring an underlying Kubernetes failure.

Frequently asked questions