Obtaining the ingress URL for an environment

You can use the CloudBees Previews API to query and obtain an exposed URL from an environment once it is in the ready phase. The URL could originate from a Kubernetes Ingress or Service resource. This is explained in general here. Before you obtain the ingress URL for an environment, you must authenticate requests by providing the API token.

If you want to configure an automated job to use an environment (for example, for an end-to-end test), you can enable automatic environment creation and updates. However, the job must wait until the environment is ready before it can be accessed.

Finding out if an environment is ready

You can use the check=ready parameter to find out if an environment is ready to be accessed and used for automation. If you specify the check=ready parameter, the HTTP status of the API call reflects the status of the queried environment. If no environment matches the search criteria, or if no matching environment is ready, the server provides the HTTP status code 429, indicating that the client should continue to poll.

Checking if an environment is ready

$ curl -sS -H 'X-Api-Token: <API_TOKEN>' \
	"<SERVER_ADDRESS>/api/v1/environments?check=ready&labels=commit-sha=<SHA>,context=<CONTEXT>,repo-name=<REPO_NAME>,pr-number=<PR_NUMBER>" \
	| jq .
{
  "message": "environment previews/env-xyz is provisioning",
  "type":"Pending"
}▼

Polling until an environment is ready

You can include the --retry option to make curl poll until an environment becomes ready. Depending on the type of application you are using the environment for, you might want to increase or decrease the values for the options --retry and --retry-max-time.

Polling until an environment is ready

$ curl -sS --retry 180 --retry-delay 1 --retry-max-time 180 \
	-H 'X-Api-Token: <API_TOKEN>' \
	"<SERVER_ADDRESS>/api/v1/environments?check=ready&labels=commit-sha=<SHA>,context=<CONTEXT>,repo-name=<REPO_NAME>,pr-number=<PR_NUMBER>" \
	| jq .
{
  "message": "environment previews/env-xyz is provisioning",
  "type":"Pending"
}
{
  "message": "environment previews/env-xyz is provisioning",
  "type":"Pending"
}
{
  "items": [
    {
      "metadata": {
        "name": "env-xyz",
        "namespace": "previews",
        "labels": {
          "commit-sha": "b49f34af0888c7c3cd676ba78ec64864754705be",
          "context": "default",
          "pr-number": "42",
          "repo-namespace": "sample-org",
          "repo-name": "sample-app-helm"
        }
      },
      "spec": {
        "gitSource": {
          "cloneURL": "https://github.com/mgoltzsche/sample-app-helm.git",
          "commitSHA": "b49f34af0888c7c3cd676ba78ec64864754705be"
        },
        "context": "default"
      },
      "status": {
        "phase": "ready",
        "urls": [
          {
            "url": "https://env-xyz.preview.example.org/myapp"
          }
        ]
      }
    }
  ]
}▼

Polling fails early if the environment fails to initialize. In that case, the response body provides more information.

Obtaining the ingress URL

Once the environment is ready, you can obtain the ingress URL using one of the following three alternatives.

Use this API call in your CI job to synchronize the initialization/update of an environment with an end-to-end test run.

$ curl -sS --retry 180 --retry-delay 1 --retry-max-time 180 \
	-H 'X-Api-Token: <API_TOKEN>' \
	"<SERVER_ADDRESS>/api/v1/environments?check=ready&labels=commit-sha=<SHA>,context=<CONTEXT>,repo-name=<REPO_NAME>,pr-number=<PR_NUMBER>" \
	| jq -Rre '. | fromjson | .items[0].status.urls[0].url as $url | if $url then $url else error(.message) end'
jq: error (at <stdin>:1): no environment matched the search criteria - maybe environment auto-creation is disabled?
jq: error (at <stdin>:2): environment previews/env-xyz is provisioning
jq: error (at <stdin>:3): environment previews/env-xyz is provisioning
jq: error (at <stdin>:4): environment previews/env-xyz is provisioning
https://env-xyz.preview.example.org/myapp▼

$ curl -sS --retry 180 --retry-delay 1 --retry-max-time 180 \
	-H 'X-Api-Token: <API_TOKEN>' \
	"<SERVER_ADDRESS>/api/v1/environments?check=ready&labels=commit-sha=<SHA>,context=<CONTEXT>,repo-name=<REPO_NAME>,pr-number=<PR_NUMBER>" \
	| awk '/"url":"http[^"]+/ {found=1; print gensub(/.+(http[^"]+).+/, "\\1", "g", $0); next} {print > "/dev/stderr"}; END {exit !found}' -
{"message":"no environment matched the search criteria","type":"NoMatch"}
{"message":"environment previews/env-xyz is provisioning","type":"Pending"}
{"message":"environment previews/env-xyz is provisioning","type":"Pending"}
{"message":"environment previews/env-xyz is provisioning","type":"Pending"}
https://env-xyz.preview.example.org/myapp▼

$ timeout 180s wget -qO - --tries=180 --retry-on-http-error=429,502,503,504 \
	--header='X-Api-Token: <API_TOKEN>' \
	"<SERVER_ADDRESS>/api/v1/environments?check=ready&labels=commit-sha=<SHA>,context=<CONTEXT>,repo-name=<REPO_NAME>,pr-number=<PR_NUMBER>" \
	| jq -re '.items[0].status.urls[0].url'
https://env-xyz.preview.example.org/myapp▼

While polling, you can use either jq or awk to log intermediate environment states to stderr. On success, the ingress URL is logged to stdout. This allows you to capture the URL in an environment variable and log status and error information.

If you use wget for polling, only the last response body is provided on success. Thus, to log a meaningful error message when polling failed, you should repeat the request one more time using wget’s --content-on-error=on option.

There are wget distributions that don’t support retries, such as busybox.