Akamai Operator

A Kubernetes operator for managing Akamai Properties through the Property Manager API. This operator is OLM (Operator Lifecycle Manager) compatible and allows you to manage Akamai edge delivery configurations as Kubernetes custom resources.

Features

• Declarative Property Management: Define Akamai properties as Kubernetes custom resources
• Full Lifecycle Management: Create, update, and delete Akamai properties through Kubernetes
• Hostname Management: Automatic management of property hostnames and edge hostname assignments
• OLM Compatible: Can be installed and managed through Operator Lifecycle Manager
• EdgeGrid Authentication: Secure authentication using Akamai EdgeGrid
• Status Reporting: Real-time status updates with property versions and deployment state
• Rule Configuration: Support for complex property rules, behaviors, and criteria
• Automatic Activation: Optional automatic activation to staging and production networks

Prerequisites

• Kubernetes cluster (v1.19+)
• Akamai API credentials with Property Manager permissions
• kubectl configured to access your cluster

Quick Start

1. Install the Operator

Option A: Using OLM (Recommended for production)

# Install OLM if not already installed
curl -sL https://github.com/operator-framework/operator-lifecycle-manager/releases/download/v0.25.0/install.sh | bash -s v0.25.0

# Install the Akamai Operator
kubectl apply -f https://github.com/mmz-srf/akamai-operator/releases/latest/download/akamai-operator.yaml

Option B: Direct Installation

# Clone the repository
git clone https://github.com/mmz-srf/akamai-operator.git
cd akamai-operator

# Install CRDs
make install

# Deploy the operator
make deploy

2. Configure Akamai Credentials

Create a secret with your Akamai API credentials:

kubectl create secret generic akamai-credentials \
  --from-literal=host="akaa-baseurl-xxxxxxxxxxx-xxxxxxxxxxxxx.luna.akamaiapis.net" \
  --from-literal=client_token="akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx" \
  --from-literal=client_secret="xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx" \
  --from-literal=access_token="akab-xxxxxxxxxxxxxxxx-xxxxxxxxxxxxxxxx" \
  --namespace=akamai-operator-system

Note: The operator watches for cluster-scoped AkamaiProperty resources across all namespaces, but the operator itself and its credentials are deployed in the akamai-operator-system namespace.

3. Create an Akamai Property

Create a sample property configuration:

apiVersion: akamai.com/v1alpha1
kind: AkamaiProperty
metadata:
  name: my-website
spec:
  propertyName: "my-website.com"
  contractId: "ctr_C-1234567"
  groupId: "grp_12345"
  productId: "prd_Fresca"
  hostnames:
    - cnameFrom: "my-website.com"
      cnameTo: "my-website.com.edgesuite.net"
      certProvisioningType: "CPS_MANAGED"
  rules:
    name: "default"
    behaviors:
      - name: "origin"
        options:
          originType: "CUSTOMER"
          hostname: "origin.my-website.com"
          forwardHostHeader: "REQUEST_HOST_HEADER"
  activation:
    network: "PRODUCTION"
    notifyEmails:
      - "[email protected]"

Apply the configuration:

kubectl apply -f my-property.yaml

4. Monitor the Property

Check the status of your property:

# List all Akamai properties
kubectl get akamaiproperties

# Get detailed status
kubectl describe akamaiproperty my-website

Configuration

AkamaiProperty Custom Resource

The AkamaiProperty custom resource supports the following specifications:

Required Fields

• propertyName: Name of the Akamai property
• contractId: Akamai contract ID (format: ctr_C-XXXXXXX)
• groupId: Akamai group ID (format: grp_XXXXX)
• productId: Akamai product ID (e.g., prd_Fresca)

Optional Fields

• hostnames: Array of hostname configurations
• rules: Property rules configuration with behaviors and criteria
• edgeHostname: Edge hostname configuration
• activation: Activation configuration for deploying the property to Akamai networks

Hostnames Configuration

The operator fully manages property hostnames, automatically detecting changes and updating property versions when hostnames are added, removed, or modified.

hostnames:
  - cnameFrom: "www.example.com"
    cnameTo: "example.com.edgesuite.net"
    certProvisioningType: "CPS_MANAGED"
  - cnameFrom: "api.example.com"
    cnameTo: "example.com.edgekey.net"
    certProvisioningType: "CPS_MANAGED"

Fields:

• cnameFrom (required): The hostname to serve through Akamai
• cnameTo (required): The edge hostname target
• certProvisioningType (optional): Certificate provisioning type (CPS_MANAGED or DEFAULT)

See HOSTNAME_MANAGEMENT.md for detailed documentation.

Rules Configuration

The rules system supports nested rules with criteria and behaviors:

rules:
  name: "default"
  behaviors:
    - name: "origin"
      options:
        originType: "CUSTOMER"
        hostname: "origin.example.com"
  children:
    - name: "Static Assets"
      criteria:
        - name: "fileExtension"
          options:
            matchOperator: "IS_ONE_OF"
            values: ["css", "js", "png"]
      behaviors:
        - name: "caching"
          options:
            behavior: "MAX_AGE"
            ttl: "7d"

Activation Configuration

The operator supports automatic activation of properties to Akamai's staging and production networks:

activation:
  # Target network: STAGING or PRODUCTION
  network: "STAGING"
  # Email addresses to notify when activation status changes
  notifyEmails:
    - "[email protected]"
    - "[email protected]"
  # Descriptive note for the activation
  note: "Automated activation via Kubernetes operator"
  # Skip acknowledging individual warnings (default: false)
  acknowledgeAllWarnings: true
  # Enable fast metadata push (default: true)
  fastPush: true
  # Ignore HTTP errors during fast metadata push (default: true)
  ignoreHttpErrors: true
  # Use fast fallback for quick rollback within 1 hour (default: false)
  useFastFallback: false

Activation Process:

1. Automatic Activation: When an activation section is specified, the operator will automatically activate new property versions
2. Status Tracking: The operator tracks activation status and updates the resource status accordingly
3. Network Support: Supports both STAGING and PRODUCTION networks
4. Notifications: Email notifications are sent based on the notifyEmails configuration
5. Rollback Support: Fast fallback can be enabled for quick rollback within one hour of activation

Activation Status Fields:

The operator provides detailed activation status in the resource status:

• stagingVersion: Currently active version on staging
• productionVersion: Currently active version on production
• stagingActivationId: ID of the current staging activation
• productionActivationId: ID of the current production activation
• stagingActivationStatus: Status of staging activation (PENDING, ACTIVE, FAILED)
• productionActivationStatus: Status of production activation (PENDING, ACTIVE, FAILED)

Authentication

The operator uses Akamai EdgeGrid authentication. You need to provide the following credentials:

1. Host: Your API endpoint hostname
2. Client Token: Your client token
3. Client Secret: Your client secret
4. Access Token: Your access token

These can be obtained from the Akamai Control Center under "Identity & Access Management" > "API User".

Examples

Basic Website Property

apiVersion: akamai.com/v1alpha1
kind: AkamaiProperty
metadata:
  name: basic-website
spec:
  propertyName: "basic-website.com"
  contractId: "ctr_C-1234567"
  groupId: "grp_12345"
  productId: "prd_Fresca"
  hostnames:
    - cnameFrom: "basic-website.com"
      cnameTo: "basic-website.com.edgesuite.net"
  rules:
    name: "default"
    behaviors:
      - name: "origin"
        options:
          originType: "CUSTOMER"
          hostname: "origin.basic-website.com"
  activation:
    network: "PRODUCTION"
    notifyEmails:
      - "[email protected]"

Advanced Property with Multiple Rules

See config/samples/akamai_v1alpha1_akamaiproperty.yaml for a comprehensive example.

Monitoring and Troubleshooting

Check Operator Logs

kubectl logs -n akamai-operator-system deployment/akamai-operator-controller-manager

Property Status

The operator reports detailed status information:

status:
  propertyId: "prp_123456"
  latestVersion: 2
  stagingVersion: 1
  productionVersion: 1
  phase: "Ready"
  conditions:
    - type: "Ready"
      status: "True"
      reason: "PropertyReady"
      message: "Property is ready"

Common Issues

1. Authentication Errors: Verify your API credentials are correct
2. Contract/Group Not Found: Ensure the contract and group IDs are valid
3. Property Creation Failed: Check the operator logs for detailed error messages

Development

Building from Source

# Clone the repository
git clone https://github.com/mmz-srf/akamai-operator.git
cd akamai-operator

# Build the operator
make build

# Run tests
make test

# Build Docker image
make docker-build IMG=your-registry/akamai-operator:latest

Running Tests

The project includes comprehensive unit tests for all major functionality:

# Run all tests
go test ./...

# Run with verbose output
go test ./... -v

# Run with coverage
go test ./... -cover

See Testing Documentation for detailed information about available tests and how to write new ones.

Local Development

# Install CRDs
make install

# Run the operator locally
make run

Contributing

We welcome contributions! Please see CONTRIBUTING.md for guidelines.

License

This project is licensed under the Apache License 2.0. See LICENSE for details.

Support

For support questions, please:

1. Check the troubleshooting guide
2. Review existing issues
3. Create a new issue with detailed information

For Akamai API questions, consult the Property Manager API documentation.