Scope Creation Guide

Scopes represent landing zones for different environments (like development, staging, production) or instances of your application. They define where and how your application runs.

Scopes belong to applications which belong to namespaces, accounts, and organizations.

Creating a New Scope

Creating a scope involves discovering available dimensions, fetching scope types with their configuration schemas, and creating the scope with the required parameters.

Important Requirements for Kubernetes Scopes

If you're creating a Kubernetes scope, ensure your application meets these requirements before deploying:

• Dockerfile Required: Your application must include a Dockerfile in the repository for building the Docker image
• Listen Port: Your application should typically listen on port 8080
• Health Endpoint: Your application must expose a /health endpoint that returns a successful status (200 OK) for health checks to work properly

Step 1: Discover Available Dimensions

Dimensions are labels that categorize scopes (e.g., environment: production, stage, test). Before creating a scope, check what dimensions are available. If a dimension exists for your application, you must fill it for the scope, for example if country and environment exists you need to fill both.

API Call:

Method: GET
Endpoint: /dimension?nrn=organization=<org_id>:account=<account_id>:namespace=<namespace_id>:application=<application_id>

Response Example:

{
  "results": [
    {
      "id": 209213675,
      "name": "Environment",
      "nrn": "organization=4",
      "slug": "environment",
      "status": "active",
      "order": 1,
      "values": [
        {
          "id": 1476997668,
          "name": "Production",
          "slug": "production",
          "status": "active"
        },
        {
          "id": 1855672260,
          "name": "Stage",
          "slug": "stage",
          "status": "active"
        },
        {
          "id": 86928740,
          "name": "Test",
          "slug": "test",
          "status": "active"
        }
      ]
    }
  ]
}

Important:

• Dimensions can be zero (no dimensions available)
• The slug field is what you'll use when creating the scope
• Only dimensions with "status": "active" can be used

Step 2: Fetch Available Scope Types

Scope types define the infrastructure where your application will run (e.g., Kubernetes, Serverless, etc.) and include the configuration schema.

API Call:

Method: GET
Endpoint: /scope_type?nrn=organization=<org_id>:account=<account_id>:namespace=<namespace_id>:application=<application_id>&status=active&include=capabilities

Response Example:

{
  "results": [
    {
      "id": 1024852107,
      "provider": "480c7522-5a93-439a-8255-f30a54e82f1e",
      "name": "Kubernetes Custom",
      "status": "active",
      "description": "Allows you to deploy applications in Kubernetes",
      "type": "custom",
      "capabilities": {
        "asset_type": "docker-image",
        "custom_domains": {
          "enabled": true
        },
        "stop_scope": true,
        "schedule_stop_scope": true,
        "kill_instance": false,
        "stop_autoscalling": false,
        "switch_traffic": true,
        "wait_for_instances": false
      },
      "parameters": {
        "schema": {
          "type": "object",
          "required": [
            "ram_memory",
            "visibility",
            "autoscaling",
            "health_check",
            "scaling_type",
            "cpu_millicores",
            "fixed_instances",
            "scheduled_stop",
            "additional_ports",
            "continuous_delivery",
            "protocol",
            "security"
          ],
          "properties": {
            "ram_memory": {
              "type": "integer",
              "title": "RAM Memory",
              "default": 256,
              "description": "Amount of RAM memory to allocate to the container (in MB)"
            },
            "visibility": {
              "type": "string",
              "title": "Visibility",
              "default": "public",
              "description": "Define whether the scope is publicly accessible or private to your account"
            },
            "cpu_millicores": {
              "type": "integer",
              "title": "CPU Millicores",
              "default": 500,
              "description": "Amount of CPU to allocate (in millicores, 1000m = 1 CPU core)"
            },
            "scaling_type": {
              "enum": ["fixed", "auto"],
              "type": "string",
              "title": "Scaling Type",
              "default": "fixed"
            },
            "fixed_instances": {
              "type": "integer",
              "title": "Number of Instances",
              "default": 1
            },
            "health_check": {
              "type": "object",
              "properties": {
                "enabled": {
                  "type": "boolean",
                  "default": true
                },
                "type": {
                  "enum": ["HTTP", "TCP"],
                  "type": "string",
                  "default": "HTTP"
                },
                "path": {
                  "type": "string",
                  "default": "/health"
                }
              }
            }
          }
        }
      }
    },
    {
      "id": 1628766494,
      "provider": "1a60b124-2cee-49e4-bc18-182bb869e59e",
      "name": "Scheduled Task",
      "status": "active",
      "description": "Allows you to deploy periodic jobs in Kubernetes",
      "type": "custom",
      "capabilities": {
        "asset_type": "docker-image",
        "stop_scope": true
      },
      "parameters": {
        "schema": {
          "type": "object",
          "required": [
            "ram_memory",
            "cpu_millicores",
            "cron",
            "concurrency_policy"
          ],
          "properties": {
            "ram_memory": {
              "type": "integer",
              "title": "RAM Memory",
              "default": 64
            },
            "cpu_millicores": {
              "type": "integer",
              "title": "CPU Millicores",
              "default": 500
            },
            "cron": {
              "type": "string",
              "title": "Task Frequency",
              "description": "Cron expression for scheduling"
            },
            "concurrency_policy": {
              "type": "string",
              "default": "Forbid"
            }
          }
        }
      }
    }
  ]
}

Understanding Scope Types:

• provider: The provider ID to use when creating the scope
• type: Usually "custom" for custom configurations
• capabilities: Features available for this scope type
• parameters.schema: JSON Schema defining required and optional configuration
• default values: Most properties have defaults that can be used as-is

Step 3: Create the Scope

Once you have the dimensions and scope type schema, you can create the scope with the required configuration.

Basic Kubernetes Scope (with defaults)

API Call:

Method: POST
Endpoint: /scope
Body: '{
  "application_id": 60,
  "name": "production",
  "type": "custom",
  "provider": "480c7522-5a93-439a-8255-f30a54e82f1e",
  "dimensions": {
    "environment": "production"
  },
  "capabilities": {
    "ram_memory": 256,
    "visibility": "public",
    "cpu_millicores": 500,
    "scaling_type": "fixed",
    "fixed_instances": 1,
    "health_check": {
      "enabled": true,
      "type": "HTTP",
      "path": "/health",
      "initial_delay_seconds": 30,
      "period_seconds": 10,
      "timeout_seconds": 5
    },
    "autoscaling": {
      "min_replicas": 1,
      "max_replicas": 5,
      "target_cpu_utilization": 70,
      "target_memory_enabled": false
    },
    "scheduled_stop": {
      "enabled": false,
      "timer": "3600"
    },
    "additional_ports": [],
    "continuous_delivery": {
      "enabled": false,
      "branches": ["main"]
    },
    "protocol": "http",
    "security": {
      "fs_group": "root"
    }
  }
}'

Kubernetes Scope with Auto-scaling

API Call:

Method: POST
Endpoint: /scope
Body: '{
  "application_id": 60,
  "name": "staging",
  "type": "custom",
  "provider": "480c7522-5a93-439a-8255-f30a54e82f1e",
  "dimensions": {
    "environment": "stage"
  },
  "capabilities": {
    "ram_memory": 512,
    "visibility": "internal",
    "cpu_millicores": 1000,
    "scaling_type": "auto",
    "health_check": {
      "enabled": true,
      "type": "HTTP",
      "path": "/health",
      "initial_delay_seconds": 30,
      "period_seconds": 10,
      "timeout_seconds": 5
    },
    "autoscaling": {
      "min_replicas": 2,
      "max_replicas": 10,
      "target_cpu_utilization": 70,
      "target_memory_enabled": true
    },
    "scheduled_stop": {
      "enabled": false,
      "timer": "3600"
    },
    "additional_ports": [],
    "continuous_delivery": {
      "enabled": true,
      "branches": ["develop", "staging"]
    },
    "protocol": "http",
    "security": {
      "fs_group": "root"
    }
  }
}'

Understanding Scope Configuration

Common Kubernetes Parameters

Resource Allocation:

• ram_memory: RAM in MB (64, 128, 256, 512, 1024, 2048, 4096, 8192, 16384)
• cpu_millicores: CPU in millicores (100-4000, where 1000m = 1 CPU core)

Visibility:

• public: Accessible from the internet
• internal: Only accessible within your organization

Scaling:

• scaling_type: "fixed" or "auto"
• fixed_instances: Number of instances (when scaling_type is "fixed")
• autoscaling: Configuration for auto-scaling (when scaling_type is "auto")
  • min_replicas: Minimum number of instances
  • max_replicas: Maximum number of instances
  • target_cpu_utilization: CPU threshold for scaling (50-90%)
  • target_memory_enabled: Whether to scale based on memory

Health Check:

• enabled: Enable health checks
• type: "HTTP" or "TCP"
• path: HTTP path for health checks (when type is "HTTP")
• initial_delay_seconds: Seconds to wait before starting health checks
• period_seconds: Seconds between health checks
• timeout_seconds: Seconds to wait for a health check response

Continuous Delivery:

• enabled: Enable automatic deployment from Git branches
• branches: Array of Git branches to monitor

Protocol:

• http: Standard API or frontend
• sse: HTTP streaming or SSE connection

Additional Ports:

• Array of extra ports to expose (e.g., for gRPC)
• Each port has a port number and type (e.g., "GRPC")

Scheduled Stop:

• enabled: Enable automatic stopping
• timer: When to stop ("3600" = 1 hour, "10800" = 3 hours, "21600" = 6 hours, "43200" = 12 hours, "tonight")

Common Workflow Example

Creating a Production Kubernetes Scope

1. Get application details:

   Method: GET
   Endpoint: /application/:id

2. Check available dimensions:

   Method: GET
   Endpoint: /dimension?nrn=organization=4:account=17:namespace=36:application=60

3. List available scope types:

   Method: GET
   Endpoint: /scope_type?nrn=organization=4:account=17:namespace=36:application=60&status=active&include=capabilities

4. Create the scope:

   Method: POST
   Endpoint: /scope
   Body: '{
     "application_id": 60,
     "name": "production",
     "type": "custom",
     "provider": "480c7522-5a93-439a-8255-f30a54e82f1e",
     "dimensions": {
       "environment": "production"
     },
     "capabilities": {
       "ram_memory": 2048,
       "visibility": "public",
       "cpu_millicores": 1000,
       "scaling_type": "auto",
       "health_check": {
         "enabled": true,
         "type": "HTTP",
         "path": "/health",
         "initial_delay_seconds": 30,
         "period_seconds": 10,
         "timeout_seconds": 5
       },
       "autoscaling": {
         "min_replicas": 3,
         "max_replicas": 10,
         "target_cpu_utilization": 70,
         "target_memory_enabled": true
       },
       "scheduled_stop": {
         "enabled": false,
         "timer": "3600"
       },
       "additional_ports": [],
       "continuous_delivery": {
         "enabled": true,
         "branches": ["main"]
       },
       "protocol": "http",
       "security": {
         "fs_group": "root"
       }
     }
   }'

Creating Multiple Scopes for Different Environments

1. Create production scope:

   Method: POST
   Endpoint: /scope
   Body: '{
     "application_id": 60,
     "name": "production",
     "type": "custom",
     "provider": "480c7522-5a93-439a-8255-f30a54e82f1e",
     "dimensions": {
       "environment": "production"
     },
     "capabilities": {
       "ram_memory": 2048,
       "cpu_millicores": 1000,
       "scaling_type": "auto",
       "autoscaling": {
         "min_replicas": 3,
         "max_replicas": 10
       }
     }
   }'

2. Create staging scope:

   Method: POST
   Endpoint: /scope
   Body: '{
     "application_id": 60,
     "name": "staging",
     "type": "custom",
     "provider": "480c7522-5a93-439a-8255-f30a54e82f1e",
     "dimensions": {
       "environment": "stage"
     },
     "capabilities": {
       "ram_memory": 1024,
       "cpu_millicores": 500,
       "scaling_type": "fixed",
       "fixed_instances": 2
     }
   }'

Listing Scopes

To view all scopes for an application:

API Call:

Method: GET
Endpoint: /scope?application_id=<application_id>

Reading a Specific Scope

To get details about a specific scope:

API Call:

Method: GET
Endpoint: /scope/:id

Important Notes

• Scope names must be unique within an application
• Provider validation: The provider must be available for your organization and application
• Schema compliance: The capabilities object must match the scope type's schema
• Default values: Use default values from the schema when unsure about configuration
• Dimensions: Can be empty {} if no dimensions are available or required
• Resource limits: RAM and CPU allocations have specific allowed values defined in the schema
• Health checks: Recommended for production scopes to ensure proper monitoring
• Auto-scaling: Only available when scaling_type is set to "auto"
• Continuous delivery: Enables automatic deployment when code is pushed to specified branches
• Scheduled stop: Useful for development/test environments to save costs

Next Steps

After creating a scope:

1. Set up parameters specific to this scope
2. Create your first build and deployment
3. Configure monitoring and alerts
4. Set up custom domains (if supported by the scope type)

See the Scope Read guide for how to view and manage your scopes, and the Deployment Create guide for deploying to your scope.