Mendix for Private Cloud Deploy API

Last modified: April 18, 2024

This document is about Private Cloud API. For Private Mendix Platform API, see Private Mendix Platform API Documentation.

1 Introduction

The Mendix for Private Cloud Deploy API allows you to manage application environments deployed to your private cloud using the Mendix Operator. You can use the API to do the following:

Download the configuration tool, mxpc-cli, for your operating system
Create, update, or delete a cluster
Create, update, or delete a namespace
Create or delete an environment
Update an environment and deploy and manage an app in an environment through changes to the environment manifest

The Mendix for Private Cloud Deploy API is for connected private cloud clusters only.

The Global Operator installation is not yet available in Deploy API.

2 Using the API

To help you work with the Mendix for Private Cloud Build API, the following sections of this document describe how to authenticate for the API, how to manage asynchronous API calls, and what to keep in mind when assigning unique IDs for the resources.

2.1 Authentication

Authentication for the API uses a personal access token (PAT).

2.1.1 Generating a PAT

To generate a PAT, see the Personal Access Tokens section of Mendix Profile.

Select the following as scopes:

mx:deployment:read – to perform GET operations
mx:deployment:write – to perform all operations (GET, POST, PUT, and DELETE)

For operations related to deployment packages (such as Create, Upload, Delete, and Retrieve), you need to create PAT tokens as specified in Mendix for Private Cloud Build API: Using the PAT.

Store the {GENERATED_PAT} value in a safe location, so you can use it to authorize your Mendix for Private Cloud API calls.

2.1.2 Scopes explanation

Operation	Scopes
Get namespace manifest	`mx:deployment:read` or `mx:deployment:write`
Get namespaces manifest	`mx:deployment:read` or `mx:deployment:write`
Get cluster manifest	`mx:deployment:read` or `mx:deployment:write`
Get clusters manifest	`mx:deployment:read` or `mx:deployment:write`
Create cluster	`mx:deployment:write`
Update cluster	`mx:deployment:write`
Delete cluster	`mx:deployment:write`
Create namespace	`mx:deployment:write`
Update namespace	`mx:deployment:write`
Delete namespace	`mx:deployment:write`
Get environment manifest	`mx:deployment:read` or `mx:deployment:write`
Create environment	`mx:deployment:write`
Update environment	`mx:deployment:write`
Delete environment	`mx:deployment:write`
Get Job	`mx:deployment:read` or `mx:deployment:write`

2.1.3 Using the PAT

Each request must contain an Authorization header with the value MxToken {GENERATED_PAT}.

To authenticate calls when using the Open API specification below, click Authorize and use the value MxToken {GENERATED_PAT}.

2.2 Managing Asynchronous Jobs

All resource manipulation API calls are processed asynchronously. In the response, there is an id which you can use with the GET /jobs/… call to get the status of the asynchronous job.

Each asynchronous call will also return a Location header that references the URL where the result of that job can be found, for example, https://privatecloud.mendixcloud.com/api/v3/jobs/59464c21-0558-47a9-8d3d-ccc7057dc359. This can be used as an alternative to GET /jobs/….

Once GET /jobs/… or the equivalent HTTP call returns a response with "status": "finished", you can verify the manifest for the resource by using a GET {RESOURCE} API call. For example, when updating a cluster, you can use GET /clusters/{clusterId} to verify the cluster manifest.

2.3 Assigning IDs

The API does not generate unique UUIDs for the resources. You must generate your own IDs, which must be unique. If the IDs are not unique, the asynchronous job which creates the resource will fail.

3 Examples

The following sections of this document contain sample usage scenarios for the API.

3.1 Using the API to Update the Cluster and Namespace

The following steps will create a cluster, register and install a namespace, add or update a cluster member, and enable development mode for the namespace.

Set up your authentication PAT.
Prepare a manifest for your new cluster.
Make the API call POST /clusters using the cluster manifest to create a new cluster.
Verify that the job is successful using the process described in Managing Asynchronous Jobs.
Prepare a manifest for your new namespace.
Make the API call POST /clusters/{clusterId}/namespaces using the {clusterId} of the cluster you just created and your namespace manifest to create a new namespace.
Verify that the job is successful using the process described in Managing Asynchronous Jobs.
Call GET /cli to retrieve all the available CLI versions.
Call POST/cli/… to download the correct version on mxpc-cli. This call will validate the provided path and query parameters and then redirect you to the CDN URL where the correct version of mxpc-cli is stored.
After mxpc-cli has been downloaded use the command ./mxpc-cli installer -n new-operator -i {namespaceID} -s {secret} to install and configure the Mendix operator in the namespace. {secret} is the secret you provided in the manifest when creating the namespace. Once the installer has run, the namespace is ready to use (namespace installed, agent connected, database and store plans configured, ingress configured, registry configured).
Call GET /clusters to retrieve all the clusters that have been created. Copy the clusterId from the response of this call.
Make an API call POST /clusters/{clusterId} to add/update the cluster member. You can get the manifest for this update request from GET /clusters/{clusterId}.
Make an API call POST /clusters/{namespaceId} to update the namespace development mode and set enableDevelopmentMode to true . You can get the manifest for this update request from GET /clusters/{namespaceId}.

If required, the invitation for the cluster/namespace member can be auto-accepted by setting autoAcceptInvite to true in the update cluster/namespace API request.

3.2 Using the API to Restart an App

The following steps will restart an app by setting the number of instances to zero and then setting it back to the number of instances required.

Set up your authentication PAT.
Call GET /apps/{appId}/namespaces/{namespaceId}/environments/{environmentId} to get the environment manifest for your app environment.
Change the container.instances to 0 in the manifest.
Call PUT /apps/{appId}/namespaces/{namespaceId}/environments/{environmentId} using the updated manifest.
Verify that the job is successful using the process described in Managing Asynchronous Jobs.

At this point, your app is stopped and you will not be able to access it using the appURL.
Change the container.instances in the manifest to the number of instances you want to run.
Call PUT /apps/{appId}/environments/namespaces/{namespaceId}/{environmentId} using the updated manifest.
Verify that the job is successful, as before.

Your app is available once more.

3.3 Using the API to Deploy an App

The following steps will create a cluster, create a namespace, and create an environment with a running app.

Set up your authentication PAT.
Prepare a manifest for your new cluster.
Make the API call POST /clusters using the cluster manifest to create a new cluster.
Verify that the job is successful using the process described in Managing Asynchronous Jobs.
Prepare a manifest for your new namespace.
Make the API call POST /clusters/{clusterId}/namespaces using the {clusterId} of the cluster you just created and your namespace manifest to create a new namespace.
Verify that the job is successful using the process described in Managing Asynchronous Jobs.
Call GET /cli to retrieve all the available CLI versions.
Call POST/cli/… to download the correct version on mxpc-cli. This call will validate the provided path and query parameters and then redirect you to the CDN URL where the correct version of mxpc-cli is stored.
After mxpc-cli has been downloaded use the command ./mxpc-cli installer -n new-operator -i {namespaceID} -s {secret} to install and configure the Mendix operator in the namespace. {secret} is the secret you provided in the manifest when creating the namespace. Once the installer has run, the namespace is ready to use (namespace installed, agent connected, database and store plans configured, ingress configured, registry configured).
Create a DeploymentPackage in the Private Cloud Portal. You can create a deployment package by using the Mendix for Private Cloud Build API. Once you create a deployment package, you can retrieve the packageId using the GET /apps/{appId}/packages response.
Prepare a manifest for your new environment. Either use the model in the OpenAPI spec file or get the manifest of an existing environment (by calling GET /apps/{appId}/namespaces/{namespaceId}/environments/{environmentId}, for example) and change where required. Remember to use the {clusterID} and {namespace} values for the provider using the cluster and namespace you have just created, and use the ID of the deployment package you have just created as the packageId.
Make the API call POST /apps/{appId}/environments using the environment manifest to create a new environment.
Verify that the job is successful using the process described in Managing Asynchronous Jobs.
Now you can access the application at the appURL which is returned from GET /apps/{appId}/namespaces/{namespaceId}/environments/{environmentId} of the environment.

Please note that there is a limited support for Custom permissions in Deploy APIs.

4 API Reference

Please note that the fields marked as non-editable in the OpenAPI .yaml file are used for read-only purposes. Any modifications made to the values of these fields will be ignored.

Feedback

Was this page helpful?

Glad to hear it! Thank you for your response.

Sorry to hear that. Please tell us how we can improve.