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

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    workspaceUuid: "<workspace-uuid>"
4    clusterId: "<cluster-id>"
5    releaseName: "my-deployment"
6    image: "quay.io/myorg/airflow:v1.2.3"
7    runtimeVersion: "12.1.0"
8    deployRevisionDescription: "CI/CD Pipeline Deploy"
9  ) {
10    id
11    status
12  }
13}

The mutation accepts the following fields:

  • workspaceUuid: The ID of the Workspace that contains the Deployment. You can provide workspaceLabel instead. One of the two is required.
  • clusterId: The ID of the cluster that hosts the Deployment.
  • 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    label: "my-deployment"
5    dagDeployment: {
6      type: volume
7      nfsLocation: "192.168.0.1:/dags"
8    }
9  ) {
10    id
11    releaseName
12  }
13}

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    workspaceUuid: "<workspace-uuid>"
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.