ComputeSphereLearn
Console
Learning paths / Deploy on ComputeSphere / Deploy as code

computesphere.yaml: your deployment as code

Reading · 7 min · Module 8, lesson 2 of 655 min left in this module

Module 8 · Deploy as codeLesson 2 of 6

Goal: Read and write a computesphere.yaml that declares a project, its environments and its services.

3:35 · captions and chapters · narrated with an AI-generated voice
Transcript

Narration uses an AI-generated voice.

[00:00] Where we're going

By the end of this video, you'll read and write a computesphere.yaml. That's your deployment, written down in one file. It lives in your repository, it gets reviewed like code, and it deploys the same way every time.

[00:14] YAML in five lines

Here's the smallest one. But first, a little YAML. Key, colon, value sets one field. Indenting by two spaces puts fields inside the one above. A line that starts with a dash is one item in a list. And quote values that could be misread, like the version, two. One more: a hash starts a comment. We'll see one shortly.

[00:40] One service

This file is complete. A version, and a list of services. Each service needs a name, and a type. Here, a web service. Then whatever that type needs. A web service runs an image, and it needs a port. You don't have to write this by hand, either. Deploy with the write flag, and the CLI saves this file for you.

So what happens if we change one line, and delete the port?

Apply it, and it's rejected. Port is required. Nothing was created. The file is checked before anything runs.

[01:18] Project, environments, services

Now a bigger one. Here's the shop from Module 2, going to staging and prod. The project and environments come first. On apply, each environment is found by name, or created if it's missing. And there's our comment. The region is a name from the regions list. Then the services. This time there are two: web, and a background worker called emails.

Now, one thing to notice. Services go into every listed environment. So staging gets its own web and emails, and so does prod. Overrides change a service in one environment. Web runs two spherelets, but just one in staging. And fromService fills in web's public address when you apply, so nobody copies it by hand.

[02:07] Apply it

Let's apply one for real, on a fresh project. Same shape: a project, a staging environment, and one web service. It also sets a health check path, and one variable, the greeting.

Then one command. The web service is created in staging. And once its deployment finishes, it's Running, with its own address. Let's ask it. Hello from the manifest.

And here it is in the console. Running, in staging. In its settings, you'll find every line from the file. The greeting. The image. One spherelet. Port eighty eighty. And the health check path, slash hello.

[02:51] Secrets stay out

One thing never goes in this file: a secret's value. Anything in Git should be treated as public. So an environment's secrets block only declares the name, with secret, true. You set the value in the console, where it's safest.

[03:08] Recap

So, a quick recap. A manifest is a version, and a list of services. Add a project and environments, and every service goes into each one. And secrets are declared, never written in. Next, we'll apply a manifest more than once, and read what each run changed. I'll see you there.

Key idea

A manifest, computesphere.yaml, describes your services in a file. It lives in your repository, gets reviewed like code, and csph turns it into running services, the same way every time.

YAML in five lines

  • key: value sets one field.
  • Indenting by two spaces puts fields inside the one above.
  • A line starting with - is one item in a list.
  • # starts a comment.
  • Quote values that could be misread, like "2".

Step 1: one service

Every csph deploy --image builds a one-service manifest behind the scenes. Add --write and csph also saves it to the current directory:

csph deploy --image quay.io/computesphere/learn-hello-web:1.0.0 --name hello-web --port 8080 --write

version: "2"
services:
  - name: hello-web
    type: web-service
    image: quay.io/computesphere/learn-hello-web:1.0.0
    port: 8080

That's complete: a version and a list of services. Each service needs a name and a type, plus what that type requires. A web service without port is rejected before anything is created.

Step 2: project, environments and a second service

Here's the shop from Module 2, deployed into staging and prod:

version: "2"

project:
  name: shop

environments:
  - name: staging
    region: us-east-1        # a name from `csph regions list`
    secrets:
      API_KEY:
        secret: true
    overrides:
      services:
        web:
          spherelets: 1
  - name: prod
    region: us-east-1
    secrets:
      API_KEY:
        secret: true

services:
  - name: web
    type: web-service
    image: quay.io/computesphere/learn-sample-api:1.0.0
    port: 8080
    plan: FLX                # the spherelet shape: FLX, MAX or PWR
    spherelets: 2
    health_check_path: /hello
    env_vars:
      GREETING: Hello from the manifest

  - name: emails
    type: background-worker
    image: ghcr.io/acme/shop-emails:1.4.0
    env_vars:
      SHOP_URL:
        fromService: web
        property: url

What each new part does:

  • project and environments: on apply, each environment is found by name, or created if missing. region is only used when creating one.
  • services are deployed into every listed environment, so staging and prod each get their own web and emails.
  • plan is the spherelet shape: FLX (Flex), MAX (Standard) or PWR (Performance). Set it on every service; without it the service is created with no shape.
  • overrides changes a service in one environment: web runs 2 spherelets, except 1 in staging.
  • fromService: web, property: url fills in web's public URL on apply, so nobody copies it by hand.

Leave out project and environments and you choose where services go when you apply (next lesson).

Service fields and environment variables
FieldUsed bySets
name, typeallUnique name; web-service, background-worker, cron-job or static-site
imageweb service, worker, cron jobThe image to run
portweb serviceRequired
sphereletsweb service, worker1 if left out
health_check_pathweb serviceThe health check's Endpoint path
schedule, commandcron jobBoth required
env_varsallVariables for this service

An environment can also have a variables block that every service shares; a service's own env_vars win on the same name. An environments list always needs a project block.

Secrets stay out of the file

Anything in Git should be treated as public, so secret values never go in the manifest. An environment's secrets block only declares the name with secret: true. Set the value in the console (lesson 5.4.1), where it's safest. Re-applying never overwrites it.

Check yourself

Your web service needs a database password. Where does its value go?

What stays out of the manifest

Volumes aren't in the file yet. Attach them in the console or with csph, and note them in your README.

In the docs