Run APIKlone your way

Sign in and set names

Registering the providers is needed once per subscription. The storage account name must be globally unique: 3 to 24 lowercase letters and numbers.

az login
az extension add --name containerapp --upgrade
az provider register --namespace Microsoft.App
az provider register --namespace Microsoft.OperationalInsights

RESOURCE_GROUP="apiklone-rg"
LOCATION="uksouth"
ENVIRONMENT="apiklone-env"
APP_NAME="apiklone"
STORAGE_ACCOUNT="apiklonedata$RANDOM"
FILE_SHARE="apiklone-data"
STORAGE_LINK="apiklonestorage"

Create the environment

az group create --name $RESOURCE_GROUP --location $LOCATION

az containerapp env create \
  --name $ENVIRONMENT \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION

Create the storage

A 5 GiB share is plenty for most teams; mock files are small.

az storage account create \
  --name $STORAGE_ACCOUNT \
  --resource-group $RESOURCE_GROUP \
  --location $LOCATION \
  --kind StorageV2 \
  --sku Standard_LRS \
  --min-tls-version TLS1_2

az storage share-rm create \
  --name $FILE_SHARE \
  --storage-account $STORAGE_ACCOUNT \
  --resource-group $RESOURCE_GROUP \
  --quota 5 \
  --enabled-protocols SMB

Attach the storage to the environment

Container Apps connects to Azure Files with the storage account key.

STORAGE_KEY=$(az storage account keys list \
  --account-name $STORAGE_ACCOUNT \
  --resource-group $RESOURCE_GROUP \
  --query "[0].value" --output tsv)

az containerapp env storage set \
  --name $ENVIRONMENT \
  --resource-group $RESOURCE_GROUP \
  --storage-name $STORAGE_LINK \
  --storage-type AzureFile \
  --azure-file-account-name $STORAGE_ACCOUNT \
  --azure-file-account-key $STORAGE_KEY \
  --azure-file-share-name $FILE_SHARE \
  --access-mode ReadWrite

Deploy APIKlone

A volume mount needs a YAML definition. Paste the block as it is; the shell fills in the variables. The mount options give the container's non-root user (ID 1000) ownership of the share.

ACTIVATION_KEY="paste-your-activation-key-here"

ENVIRONMENT_ID=$(az containerapp env show \
  --name $ENVIRONMENT \
  --resource-group $RESOURCE_GROUP \
  --query id --output tsv)

cat > apiklone.yaml <<EOF
location: $LOCATION
type: Microsoft.App/containerApps
properties:
  managedEnvironmentId: $ENVIRONMENT_ID
  configuration:
    activeRevisionsMode: Single
    ingress:
      external: true
      targetPort: 3000
      transport: auto
      allowInsecure: false
    secrets:
      - name: activation-key
        value: "$ACTIVATION_KEY"
  template:
    containers:
      - name: apiklone
        image: docker.io/apiklone/apiklone:latest
        resources:
          cpu: 0.5
          memory: 1Gi
        env:
          - name: ACTIVATION_KEY
            secretRef: activation-key
          - name: PORT
            value: "3000"
        probes:
          - type: Liveness
            httpGet:
              path: /health
              port: 3000
            periodSeconds: 30
          - type: Readiness
            httpGet:
              path: /health
              port: 3000
            periodSeconds: 10
        volumeMounts:
          - volumeName: apiklone-data
            mountPath: /app/data
    scale:
      minReplicas: 1
      maxReplicas: 1
    volumes:
      - name: apiklone-data
        storageType: AzureFile
        storageName: $STORAGE_LINK
        mountOptions: "uid=1000,gid=1000,dir_mode=0770,file_mode=0660"
EOF

az containerapp create \
  --name $APP_NAME \
  --resource-group $RESOURCE_GROUP \
  --yaml apiklone.yaml

rm apiklone.yaml   # it contains your activation key in plain text

Open it and sign in

az containerapp show \
  --name $APP_NAME \
  --resource-group $RESOURCE_GROUP \
  --query properties.configuration.ingress.fqdn --output tsv

Open https://<that-address> and sign in as admin / admin. Change that password straight away from the Team page: the address is public.

Check the data is on the share

You should see users.properties at least.

az storage file list \
  --share-name $FILE_SHARE \
  --account-name $STORAGE_ACCOUNT \
  --account-key $STORAGE_KEY \
  --query "[].name" --output tsv

Sign in and set names

Bucket names are global, so the project ID is used as a prefix.

gcloud auth login

PROJECT_ID="your-project-id"
REGION="europe-west2"
SERVICE="apiklone"
BUCKET="${PROJECT_ID}-apiklone-data"
SERVICE_ACCOUNT="apiklone-run"
SA_EMAIL="${SERVICE_ACCOUNT}@${PROJECT_ID}.iam.gserviceaccount.com"

gcloud config set project $PROJECT_ID
gcloud services enable \
  run.googleapis.com \
  secretmanager.googleapis.com \
  storage.googleapis.com

Create the storage bucket

APIKlone talks to Cloud Storage directly, so there is no volume to mount. Keep the bucket private.

gcloud storage buckets create gs://$BUCKET \
  --location=$REGION \
  --uniform-bucket-level-access \
  --public-access-prevention

Create an identity for the service

The service runs as its own service account, with access to this one bucket only. No key file is created or downloaded.

gcloud iam service-accounts create $SERVICE_ACCOUNT \
  --display-name="APIKlone on Cloud Run"

gcloud storage buckets add-iam-policy-binding gs://$BUCKET \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/storage.objectAdmin"

Store the activation key

printf '%s' "paste-your-activation-key-here" | \
  gcloud secrets create apiklone-activation-key \
    --replication-policy=automatic \
    --data-file=-

gcloud secrets add-iam-policy-binding apiklone-activation-key \
  --member="serviceAccount:$SA_EMAIL" \
  --role="roles/secretmanager.secretAccessor"

Deploy APIKlone

Setting GCS_BUCKET_NAME switches APIKlone to bucket storage. --no-cpu-throttling keeps the CPU available between requests, which the config reload and delayed async callbacks rely on.

gcloud run deploy $SERVICE \
  --image=docker.io/apiklone/apiklone:latest \
  --region=$REGION \
  --service-account=$SA_EMAIL \
  --port=3000 \
  --allow-unauthenticated \
  --set-env-vars=GCS_BUCKET_NAME=$BUCKET \
  --set-secrets=ACTIVATION_KEY=apiklone-activation-key:latest \
  --cpu=1 \
  --memory=1Gi \
  --no-cpu-throttling \
  --min-instances=1 \
  --max-instances=1

--allow-unauthenticated makes the address public, which your applications need in order to call the mocks. APIKlone's own sign-in protects the admin screens.

Open it and sign in

gcloud run services describe $SERVICE \
  --region=$REGION \
  --format='value(status.url)'

Open that address and sign in as admin / admin. Change that password straight away from the Team page.

Check the data is in the bucket

You should see users.properties at least.

gcloud storage ls gs://$BUCKET

Set names and find the network

This guide uses your account's default VPC and two of its public subnets. Use your own VPC and subnet IDs if you have a network standard.

export AWS_DEFAULT_REGION="eu-west-2"
APP="apiklone"

ACCOUNT_ID=$(aws sts get-caller-identity --query Account --output text)
VPC_ID=$(aws ec2 describe-vpcs \
  --filters Name=isDefault,Values=true \
  --query "Vpcs[0].VpcId" --output text)
read SUBNET_1 SUBNET_2 <<< $(aws ec2 describe-subnets \
  --filters Name=vpc-id,Values=$VPC_ID Name=default-for-az,Values=true \
  --query "Subnets[0:2].SubnetId" --output text)

Create the firewall rules

Three security groups, each only reachable from the one before it: internet → load balancer → container → file system.

ALB_SG=$(aws ec2 create-security-group --group-name $APP-alb \
  --description "APIKlone load balancer" --vpc-id $VPC_ID \
  --query GroupId --output text)
TASK_SG=$(aws ec2 create-security-group --group-name $APP-task \
  --description "APIKlone containers" --vpc-id $VPC_ID \
  --query GroupId --output text)
EFS_SG=$(aws ec2 create-security-group --group-name $APP-efs \
  --description "APIKlone file system" --vpc-id $VPC_ID \
  --query GroupId --output text)

aws ec2 authorize-security-group-ingress --group-id $ALB_SG \
  --protocol tcp --port 80 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress --group-id $ALB_SG \
  --protocol tcp --port 443 --cidr 0.0.0.0/0
aws ec2 authorize-security-group-ingress --group-id $TASK_SG \
  --protocol tcp --port 3000 --source-group $ALB_SG
aws ec2 authorize-security-group-ingress --group-id $EFS_SG \
  --protocol tcp --port 2049 --source-group $TASK_SG

Create the storage

An encrypted EFS file system, reachable from both subnets. The access point makes the container's non-root user (ID 1000) the owner of its own folder.

EFS_ID=$(aws efs create-file-system \
  --encrypted \
  --throughput-mode elastic \
  --tags Key=Name,Value=$APP-data \
  --query FileSystemId --output text)

# Wait until this prints "available" before continuing
aws efs describe-file-systems --file-system-id $EFS_ID \
  --query "FileSystems[0].LifeCycleState" --output text

aws efs create-mount-target --file-system-id $EFS_ID \
  --subnet-id $SUBNET_1 --security-groups $EFS_SG
aws efs create-mount-target --file-system-id $EFS_ID \
  --subnet-id $SUBNET_2 --security-groups $EFS_SG

ACCESS_POINT_ID=$(aws efs create-access-point \
  --file-system-id $EFS_ID \
  --posix-user Uid=1000,Gid=1000 \
  --root-directory 'Path=/apiklone,CreationInfo={OwnerUid=1000,OwnerGid=1000,Permissions=750}' \
  --query AccessPointId --output text)

Store the activation key

The execution role lets ECS pull the image, write logs and read this one secret, nothing else.

SECRET_ARN=$(aws secretsmanager create-secret \
  --name $APP/activation-key \
  --secret-string "paste-your-activation-key-here" \
  --query ARN --output text)

aws iam create-role --role-name $APP-execution \
  --assume-role-policy-document '{"Version":"2012-10-17","Statement":[{"Effect":"Allow","Principal":{"Service":"ecs-tasks.amazonaws.com"},"Action":"sts:AssumeRole"}]}'

aws iam attach-role-policy --role-name $APP-execution \
  --policy-arn arn:aws:iam::aws:policy/service-role/AmazonECSTaskExecutionRolePolicy

aws iam put-role-policy --role-name $APP-execution \
  --policy-name read-activation-key \
  --policy-document "{\"Version\":\"2012-10-17\",\"Statement\":[{\"Effect\":\"Allow\",\"Action\":\"secretsmanager:GetSecretValue\",\"Resource\":\"$SECRET_ARN\"}]}"

Define the container

Paste the block as it is; the shell fills in the variables.

aws logs create-log-group --log-group-name /ecs/$APP
aws ecs create-cluster --cluster-name $APP

cat > task.json <<EOF
{
  "family": "$APP",
  "networkMode": "awsvpc",
  "requiresCompatibilities": ["FARGATE"],
  "cpu": "512",
  "memory": "1024",
  "executionRoleArn": "arn:aws:iam::${ACCOUNT_ID}:role/${APP}-execution",
  "containerDefinitions": [
    {
      "name": "apiklone",
      "image": "docker.io/apiklone/apiklone:latest",
      "essential": true,
      "portMappings": [{ "containerPort": 3000, "protocol": "tcp" }],
      "environment": [{ "name": "PORT", "value": "3000" }],
      "secrets": [{ "name": "ACTIVATION_KEY", "valueFrom": "$SECRET_ARN" }],
      "mountPoints": [{ "sourceVolume": "apiklone-data", "containerPath": "/app/data" }],
      "logConfiguration": {
        "logDriver": "awslogs",
        "options": {
          "awslogs-group": "/ecs/$APP",
          "awslogs-region": "$AWS_DEFAULT_REGION",
          "awslogs-stream-prefix": "apiklone"
        }
      }
    }
  ],
  "volumes": [
    {
      "name": "apiklone-data",
      "efsVolumeConfiguration": {
        "fileSystemId": "$EFS_ID",
        "transitEncryption": "ENABLED",
        "authorizationConfig": { "accessPointId": "$ACCESS_POINT_ID" }
      }
    }
  ]
}
EOF

aws ecs register-task-definition --cli-input-json file://task.json

Create the load balancer and start the service

ALB_ARN=$(aws elbv2 create-load-balancer --name $APP \
  --subnets $SUBNET_1 $SUBNET_2 --security-groups $ALB_SG \
  --query "LoadBalancers[0].LoadBalancerArn" --output text)

TG_ARN=$(aws elbv2 create-target-group --name $APP \
  --protocol HTTP --port 3000 --vpc-id $VPC_ID \
  --target-type ip --health-check-path /health \
  --query "TargetGroups[0].TargetGroupArn" --output text)

aws elbv2 create-listener --load-balancer-arn $ALB_ARN \
  --protocol HTTP --port 80 \
  --default-actions Type=forward,TargetGroupArn=$TG_ARN

aws ecs create-service \
  --cluster $APP \
  --service-name $APP \
  --task-definition $APP \
  --desired-count 1 \
  --launch-type FARGATE \
  --network-configuration "awsvpcConfiguration={subnets=[$SUBNET_1,$SUBNET_2],securityGroups=[$TASK_SG],assignPublicIp=ENABLED}" \
  --load-balancers "targetGroupArn=$TG_ARN,containerName=apiklone,containerPort=3000" \
  --health-check-grace-period-seconds 60

assignPublicIp=ENABLED lets the container pull its image from Docker Hub from a public subnet. The container itself still only accepts traffic from the load balancer.

Add HTTPS, then sign in

Get the load balancer's address:

aws elbv2 describe-load-balancers --load-balancer-arns $ALB_ARN \
  --query "LoadBalancers[0].DNSName" --output text

CERT_ARN="arn-of-your-acm-certificate"

aws elbv2 create-listener --load-balancer-arn $ALB_ARN \
  --protocol HTTPS --port 443 \
  --certificates CertificateArn=$CERT_ARN \
  --default-actions Type=forward,TargetGroupArn=$TG_ARN

Then open https://<your-domain> and sign in as admin / admin. Change that password straight away from the Team page.