Run an image from your own pipeline

A function can run a container image built outside the platform instead of code written in the portal. The platform does not build or push that image: your pipeline pushes it to a registry, and you tell the function which image to run. The portal cannot set this up; use the CLI or the API, with functions/write in the resource group — the Owner, Contributor and Functions Operator roles have it.

What the image must do

• Serve HTTP on port 8080; the variable PORT is set to 8080.
• Answer GET /healthz with a 2xx status within 30 seconds of starting, and keep answering it. A replica gets no calls until it does; it is restarted when it has not answered after 30 seconds, or when it stops answering later.
• Serve the function's route: HTTP calls arrive with their whole path, /<route> or a path below it. Timer runs arrive as a POST to / — see Timer triggers.
• Read secrets from /secrets/env.json. The STSH_ variables are set by the code inside the platform's own runtime images, so an image of yours gets only the file — see Read the values in your code.

When the function has authentication on, the namespace's proxy checks the token before a call reaches the image; the image receives the settings in STACKSHIP_AUTH_ENABLED, STACKSHIP_OIDC_ISSUER and STACKSHIP_OIDC_AUDIENCE. The other variables a function receives are listed in Environment.

Important

The proxy's check is the only one an image of your own gets unless it checks the token itself. Workloads in the boundary can call the image directly inside the cluster, without passing the proxy, and such a call can also carry X-Stackship-User-* headers the proxy never set. If the function needs authentication, verify the token in the image as well.

Create the function

stsh functions function create my-namespace orders -g my-resource-group \
  --set source=external \
  --set runtime=Node \
  --set image=ghcr.io/acme/orders:1.4.0

• runtime is required; the image decides what actually runs.
• Without a trigger, the function is an HTTP function on /<function name> that accepts every method. To choose, add for example --set 'trigger={"type":"Http","methods":["GET","POST"]}', or --set 'trigger={"type":"Timer","schedule":"0 7 * * *"}' for a timer.

The function is deployed as soon as it is created; with the default minimum of 0 replicas it sleeps until its first call. In the portal it appears in the namespace's Functions list; its page has no Code tab.

Release a new version

Push the new image under a new tag, then point the function at it:

stsh functions function update my-namespace orders -g my-resource-group \
  --set image=ghcr.io/acme/orders:1.4.1

Use a new tag for every release. The function is redeployed only when the image reference changes, and a node that already has an image with that tag does not pull it again, so new content pushed under the same tag does not reach the function.

In a pipeline, run the CLI as a service account — see Tokens for the CLI in automation — with a role that has functions/write on the resource group, such as Functions Operator.

Which images can be used

• If your platform administrators have limited the registries images may come from, an image from any other registry is refused when you save.
• A function has no setting for registry credentials: use an image the cluster can pull without them.