Consuming Static Builds

A static build artifact can be deployed in two ways: create a workspace from it to run one instance yourself, or publish it as a managed service provider so that other teams deploy it from the service catalog.

Both need the artifact reference the export printed, for example registry.example.com/team-1/shop:v1. See Creating a Static Build for how to produce one.

Creating a workspace from an artifact

A workspace created from an artifact has no Git repository. On its first start, Codesphere writes the artifact's run-only configuration to the workspace as ci.static.yml. It appears as the CI profile static.

This needs the static-build-workspace-creation feature flag in addition to static-landscapes.

UI

1. Click Create Workspace in your resource group (team).
2. Select the Static Build tab as the source.
3. Paste the OCI artifact reference, for example registry.example.com/team-1/shop:v1.
4. Choose a name and a plan for the workspace as usual and create it.

Creating a workspace from a static build artifact.

Public API

POST /api/workspaces accepts the reference in staticBuildArtifact instead of gitUrl.

curl -X POST "https://<your-codesphere-url>/api/workspaces" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "teamId": 1,
    "name": "shop-v1",
    "planId": 21,
    "isPrivateRepo": false,
    "replicas": 1,
    "staticBuildArtifact": "registry.example.com/team-1/shop:v1"
  }'

Once the workspace is running, deploy the static profile like any other profile:

UI

1. Open Deploy in the workspace and switch to the Execution Manager.
2. Select the CI profile static.
3. Click Sync Landscape and confirm. The services start from the prebuilt images.

Public API

curl -X POST "https://<your-codesphere-url>/api/workspaces/<workspaceId>/landscape/deploy/static" \
  -H "Authorization: Bearer YOUR_API_KEY"

Templated values in the configuration, such as ${{ vault.KEY }} or ${{ workspace.env['KEY'] }}, resolve from this workspace's vault and environment. The workspace holds no source code. To change the application, change the source landscape and export a new artifact, then create a new workspace from it.

Publishing an artifact as a managed service provider

A landscape-based provider can deploy from a static build artifact instead of a Git repository. Teams then deploy the application from the service catalog, and Codesphere creates a workspace from the artifact in their team and deploys its static profile. Deployments do not depend on anyone's repository access and run exactly the exported images.

In the provider definition, set backend.landscape.staticBuildArtifact to the artifact repository without a tag instead of gitUrl. Each entry in versions then pins an artifactTag instead of gitRef and ciProfile.

name: shop
schemaVersion: v1
author: Your Team
displayName: Shop
category: ecommerce
description: The shop, deployed from a static build.
backend:
  landscape:
    staticBuildArtifact: registry.example.com/team-1/shop
configSchema:
  type: object
  properties:
    SHOP_NAME:
      type: string
      description: Name shown in the shop header
      default: My Shop
detailsSchema:
  type: object
  properties:
    hostname:
      type: string
      format: uri
versions:
  1.0.0:
    artifactTag: v1
    description: Initial release

Configuration and secrets work as for Git-based providers. configSchema properties become environment variables of the landscape and secretsSchema properties go to its vault, so reference them in the source landscape with ${{ workspace.env['SHOP_NAME'] }} and ${{ vault.KEY }} before you export. See Passing Configuration and Secrets to Landscapes.

Provider editor

1. Set the backend type to Landscape (static build artifact).
2. Enter the Artifact Repository, for example registry.example.com/team-1/shop.
3. Under Versions, add a version and enter its Artifact Tag, for example v1.
4. Fill in the remaining sections and click Publish to Catalog.

Creating a service provider from a static build artifact.

See Creating a Provider in the UI for the editor as a whole.

Public API

Publish the definition with the same endpoint as any other provider, PUT /api/managed-services/providers, with the definition above plus a scope. See Publishing and Updating a Provider.

To ship a new release, export the landscape again with a new tag, add a version that pins it and publish the definition again. Existing versions stay as they are.

Private artifacts

Codesphere reads an artifact and pulls its images with the container registry credentials of the resource group (team) that owns the consuming workspace. For a workspace you create that is your own team. For a managed service it is the team that deploys the service from the catalog, Codesphere creates the service's workspace in that team. The credentials of whoever published the provider are not used.

So a public artifact repository works everywhere. A private one needs, in every consuming team, a container registry entry whose address covers the artifact repository, for example registry.example.com/team-1. Without it the workspace fails to start, and removing the entry later breaks the next start of the service.