APC APIExample mutationsDeployment lifecycle

Upsert a Deployment with the APC API

The examples on this page show common ways to use the APC API — they’re not a complete API reference. For the full, interactive API documentation for your installation, including every available query, mutation, and type, go to https://houston.<your-base-domain>/v1, and click on the Docs tab. See Develop and test APC API queries for more on using the built-in GraphQL explorer.

You can use the upsertDeployment mutation to both create and update Deployments with all possible Deployment configurations. If you query upsertDeployment without a deploymentUuid, the APC API creates a new Deployment according to your specifications. If you specify an existing deploymentUuid, the APC API updates the Deployment with that ID. All queries to create a Deployment require specifying a workspaceUuid.

When you make upsert updates to your Airflow Deployments, you must explicitly specify all existing environment variables, otherwise, the upsert overwrites them.

The following query creates a new Deployment in a custom namespace test-new-dep and configures a Deployment environment variable AIRFLOW__CORE__COLORED_LOG_FORMAT.

1mutation upsertDeployment(
2  $workspaceUuid: Uuid,
3  $deploymentUuid: Uuid,
4  $label: String,
5  $description: String,
6  $releaseName: String,
7  $namespace: String,
8  $environmentVariables: [InputEnvironmentVariable],
9  $image: String,
10  $dockerconfigjson: JSON,
11  $version: String,
12  $airflowVersion: String,
13  $runtimeVersion: String,
14  $desiredRuntimeVersion: String,
15  $executor: ExecutorType,
16  $workers: Workers,
17  $webserver: Webserver,
18  $scheduler: Scheduler,
19  $triggerer: Triggerer,
20  $dagProcessor: DagProcessor,
21  $dagDeployment: DagDeployment,
22  $properties: JSON,
23  $cloudRole: String
24) {
25  upsertDeployment(
26    workspaceUuid: $workspaceUuid,
27    deploymentUuid: $deploymentUuid,
28    label: $label,
29    description: $description,
30    releaseName: $releaseName,
31    namespace: $namespace,
32    environmentVariables: $environmentVariables,
33    image: $image,
34    dockerconfigjson: $dockerconfigjson,
35    version: $version,
36    airflowVersion: $airflowVersion,
37    runtimeVersion: $runtimeVersion,
38    desiredRuntimeVersion: $desiredRuntimeVersion,
39    executor: $executor,
40    workers: $workers,
41    webserver: $webserver,
42    scheduler: $scheduler,
43    triggerer: $triggerer,
44    dagProcessor: $dagProcessor,
45    dagDeployment: $dagDeployment,
46    properties: $properties,
47    cloudRole: $cloudRole
48) {
49    id
50    config
51    urls {
52      type
53      url
54      __typename
55    }
56    properties
57    description
58    label
59    releaseName
60    namespace
61    status
62    type
63    version
64    workspace {
65      id
66      label
67      __typename
68    }
69    airflowVersion
70    runtimeVersion
71    desiredAirflowVersion
72    upsertedEnvironmentVariables {
73      key
74      value
75      isSecret
76      __typename
77    }
78    dagDeployment {
79      type
80      nfsLocation
81      repositoryUrl
82      branchName
83      syncInterval
84      syncTimeout
85      ephemeralStorage
86      dagDirectoryLocation
87      rev
88      sshKey
89      knownHosts
90      __typename
91    }
92    createdAt
93    updatedAt
94    __typename
95  }
96}
97{
98  "workspaceUuid": "cldemxl9502454yxe6vjlxy23",
99	"environmentVariables": [
100    {
101      "key": "AIRFLOW__CORE__COLORED_LOG_FORMAT",
102      "value": "test",
103      "isSecret": false
104    }
105  ],
106  "releaseName": "",
107  "namespace": "test-new-dep",
108  "executor": "CeleryExecutor",
109  "workers": {},
110  "webserver": {},
111  "scheduler": {
112    "replicas": 1
113  },
114  "dagProcessor": {},
115  "label": "test-new-dep",
116  "description": "",
117  "runtimeVersion": "7.2.0",
118  "properties": {
119    "extra_au": 0
120  },
121  "dagDeployment": {
122    "type": "image",
123    "nfsLocation": "",
124    "repositoryUrl": "",
125    "branchName": "",
126    "syncInterval": 1,
127    "syncTimeout": 120,
128    "ephemeralStorage": 2,
129    "dagDirectoryLocation": "",
130    "rev": "",
131    "sshKey": "",
132    "knownHosts": ""
133  }
134}

More upsertDeployment examples

The following examples show upsertDeployment used for a few other common, narrower use cases.

Deploy a pre-built image from CI/CD

This approach is useful when you need to integrate with systems that can’t use the Astro CLI directly.

1mutation {
2  upsertDeployment(
3    releaseName: "my-deployment"
4    image: "quay.io/myorg/airflow:v1.2.3"
5    runtimeVersion: "12.1.0"
6    deployRevisionDescription: "CI/CD Pipeline Deploy"
7  ) {
8    id
9    status
10  }
11}

The mutation accepts the following fields:

  • releaseName: The release name of your Deployment, following the pattern spaceyword-spaceyword-4digits. For example, infrared-photon-7780.
  • image: The full image path including registry, repository, and tag. The image must be accessible from your Astro Private Cloud data plane.
  • runtimeVersion: The Astro Runtime version that the image is based on. For example, 12.1.0.
  • deployRevisionDescription: An optional description for the deploy revision, useful for tracking deploys in the APC UI.

For more information about deploying custom images with the APC API, see Configure a custom image registry.

Configure NFS Dag deployment

Use upsertDeployment to configure a Deployment’s Dag deployment mechanism as an NFS volume mount:

1mutation {
2  upsertDeployment(
3    workspaceUuid: "<workspace-uuid>"
4    type: AIRFLOW
5    label: "my-deployment"
6    config: {
7      dagDeployment: {
8        type: "volume"
9        nfsLocation: "192.168.0.1:/dags"
10      }
11    }
12  ) {
13    id
14    releaseName
15  }
16}

For the full NFS setup, see Deploy Dags with NFS.

Skip Airflow database provisioning

To use pre-existing or managed databases, set skipAirflowDatabaseProvisioning to true in the upsertDeployment mutation:

1mutation {
2  upsertDeployment(
3    workspaceId: "<workspace-id>"
4    label: "<my-deployment-label>"
5    skipAirflowDatabaseProvisioning: true
6  ) {
7    id
8  }
9}

When using external databases, provide the connection string in your Deployment configuration. For complete setup steps with connection string examples, see Bring your own Airflow database.