Skip To Content
ArcGIS Developer
Dashboard

Edit (Deployment)

Description

The edit operation sets the scaling (replicas) and resource allocation (resources) for a specific microservice. Starting at ArcGIS Enterprise 11.2 on Kubernetes, the edit operation also allows administrators to set the node affinity and tolerations (podPlacementPolicy) that are applied to a GIS service's pods, as well as include either PersistentVolumeClaim (PVC) volumes or PVC volume templates that provide additional resources to a deployment's pods.

Scaling in ArcGIS Enterprise on Kubernetes

Either manual scaling or autoscaling can be set for a GIS service microservice using the deploymentJson parameter. Introduced at ArcGIS Enterprise on Kubernetes 10.9.1, autoscaling allows administrators to configure and deploy systems that respond to unexpected performance demands with minimal intervention and overhead. The ArcGIS Enterprise on Kubernetes autoscaling capability uses horizontal pod autoscaling, which, in response to an increase in resource usage, deploys additional pods according to the values set by the administrator.

When a specific CPU utilization threshold (averageUtilization) is crossed, ArcGIS Enterprise on Kubernetes scales the number of pods up to the maximum (max) value set in the replicas JSON object. When utilization drops, and the additional resources are no longer needed, the system scales itself back down to no lower than the minimum (min) value set in the replicas JSON object. For more information about enabling autoscaling, see the Editable properties section below.

Caution:

Though scaling properties can be updated using the edit default properties and edit deployment operations, to reduce risk of errors it is recommended that changes to scaling information is performed using the edit scaling operation.

Request parameters

ParameterDetails
deploymentJson

A JSON object that represents the properties of a microservice.

Example


deploymentJson={
  "mode": "Primary",
  "configuredState": "STARTED",
  "provider": "Postgres",
  "deploymentId": "ke84ls9uva6t7fvck8q5p",
  "name": "relational-store-primary",
  "type": "RelationalStore",
  "spec": {
    "replicas": {
      "min": 3,
      "max": 3,
      "scalingMode": "manual" //Added at 11.0
    },
    "containers": [
      {
        "name": "filebeat",
        "resources": {
          "memoryMin": "32Mi",
          "memoryMax": "50Mi",
          "cpuMin": "0.05",
          "cpuMax": "0.25"
        },
        "containerImageUrl": "container.image.com/info:1082",
        "containerImageKey": "FILEBEAT"
      },
      {
        "name": "main-container",
        "resources": {
          "memoryMin": "2Gi",
          "memoryMax": "8Gi",
          "cpuMin": "0.5",
          "cpuMax": "4"
        },
        "containerImageUrl": "container.image.com/info:1082",
        "containerImageKey": "STORE_POSTGRES"
      }
    ]
  },
  "labels": {},
  "revision": 1618223097333
}
async

(Optional)

Introduced at 10.9.1. This parameter specifies whether the operation will run synchronously or asynchronously. If false, the operation is run synchronously. If true, the operation is run asynchronously and the response returns a JSON object containing job information that can be used to track the job's status. The default value is false.

Values: true | false

f

The response format. The default format is html.

Values: html | json | pjson

Microservice properties

The following example demonstrates a full JSON object of a microservice:


{
  "mode": "Primary",
  "configuredState": "STARTED",
  "provider": "Postgres",
  "deploymentId": "ke84ls9uva6t7fvck8q5p",
  "name": "relational-store-primary",
  "type": "RelationalStore",
  "spec": {
    "replicas": {
      "min": 3,
      "max": 3,
      "scalingMode": "manual" //Added at 11.0
    },
    "containers": [
      {
        "name": "filebeat",
        "resources": {
          "memoryMin": "32Mi",
          "memoryMax": "50Mi",
          "cpuMin": "0.05",
          "cpuMax": "0.25"
        },
        "containerImageUrl": "container.image.com/info:1082",
        "containerImageKey": "FILEBEAT"
      },
      {
        "name": "main-container",
        "resources": {
          "memoryMin": "2Gi",
          "memoryMax": "8Gi",
          "cpuMin": "0.5",
          "cpuMax": "4"
        },
        "containerImageUrl": "container.image.com/info:1082",
        "containerImageKey": "STORE_POSTGRES"
      }
    ]
  },
  "labels": {},
  "revision": 1618223097333
}

The subsections below describe the individual properties included in the microservice JSON object that can, and cannot, be updated using this operation.

Editable properties

The properties below can be updated using the edit operation.

Note:

When updating the resource allocations for the microservice (cpuMin, cpuMax, memoryMin, memoryMax), the main-container resources object must be updated to affect the change.

PropertyDetails
replicas
Caution:

Though scaling properties can be updated using the edit default properties and edit deployment operations, to reduce risk of errors it is recommended that changes to scaling information is performed using the edit scaling operation.

The number of replicas for the microservice. The default value for manual scaling for min and max is 1. For manual scaling, both the min and max values must be the same.

Example of manual scaling


"replicas": {
  "min": 3,
  "max": 3,
  "scalingMode": "manual"
},

For organizations using ArcGIS Enterprise 11.2 on Kubernetes or later versions, version 2 (v2) of the autoscaling feature can be enabled by passing in the JSON object below and modifying the min, max, scalingMode, and averageUtilization values.

Note:

Prior to 11.2, the beta version of v2 autoscaling (v2beta2) could be enabled and be used to configure advanced scaling settings.

Autoscaling can be enabled by adjusting the scalingMode value to auto. The averageUtilization value will act as the CPU utilization threshold for autoscaling. If the threshold is crossed, ArcGIS Enterprise on Kubernetes scales up to the number of pods specified by the max value, and will return to no lower than the default pod level (the value set for min) once utilization decreases.

Example


"replicas": {
  "min": 1,
  "max": 10,
  "scalingMode": "auto",
  "autoscaling": {
    "hpaSpec": {
      "metrics": [
        {
          "resource": {
            "name": "cpu",
            "target": {
              "averageUtilization": "65",
              "type": "Utilization"
            }
          },
          "type": "Resource"
        }
      ],
      "hpaVersion": "autoscaling/v2"
    }
  }
},

Organizations using ArcGIS Enterprise on Kubernetes 10.9.1 can enable version 1 of the autoscaling feature by passing in the JSON object below and modifying the min, max, scalingMode, and targetCPUUtilizationPercentage values:


"replicas": {
  "min": 1,
  "max": 5,
  "scalingMode": "auto",
  "autoscaling": {
    "hpaSpec": {
      "targetCPUUtilizationPercentage": 50
    },
    "hpaVersion": "autoscaling/v1"
  }
}
podPlacementPolicy

Introduced at 11.2. Sets the node affinity or tolerations applied that will be applied the pods of a GIS service deployment. For more information on configuring node affinity or tolerations, see the Edit (Placement Policy) operation.

Example for nodeAffinity


"nodeAffinity": {
  "requiredDuringSchedulingIgnoredDuringExecution": {
    "nodeSelectorTerms": [
      {
        "matchExpressions": [
          {
            "key": "affinity",
            "operator": "In",
            "values": [
              "true"
            ]
          }
        ]
      }
    ]
  }
}

Example for tolerations


"tolerations": [
  {
    "effect": "NoExecute",
    "key": "tolerates",
    "operator": "Equal",
    "value": "true"
  }
]
volumes

Introduced at 11.2. An array that sets additional volumes for the deployment's pods to pull from. Administrators have the option to configure PVC volumes, which create a singular PVC volume that the pods of a deployment can directly request resources from, or configure PVC volume templates with the deployment, which will create separate volumes for each pod to use.

For singular PVC volumes, administrators will only need to provide the volume's ID:

Example


...
"volumes": [
  {
    "volumeId": "uadwuaj4pwkjhcst6spxx"
  }
],
...

For PVC volume templates, administrators need to provide the volume template's ID as well as the volume's purpose. The purpose specifies the types of volumes being created. Currently, the only supported purpose is GIS_SERVICE_TEMP, which designates the volumes created from the template as ephemeral volumes:

Example


...
"volumes": [
  {
    "purpose": "GIS_SERVICE_TEMP"
    "volumeConfig": "oi72y1m4q2exgzfr9uppg"
  }
],
...
resources

The minimum and maximum resource allocations for the microservice, including the minimum memory (memoryMin) and minimum CPU (cpuMin) resources required for the microservice to start. The default values for memoryMin, cpuMin, memoryMax, and cpuMax are shown in the example below.

Example


"resources": {
  "memoryMin": "500Mi",
  "memoryMax": "2Gi",
  "cpuMin": "0.125",
  "cpuMax": "2"
},

Uneditable properties

The following properties cannot be edited but are required to be passed through in the deploymentJson object:

PropertyDetails
mode

The microservice mode. A mode type of Undefined is used when the microservice is system related (Admin API, portal sharing, ingress controller, and so on). Only microservices related to an ArcGIS service type return Dedicated or Shared for this property.

Values: Shared | Dedicated | Undefined | Primary | Standby | Coordinator

provider

The microservice provider. Only microservices related to an ArcGIS service type have a provider type. A provider type of Undefined is used for microservices that are not service related (Admin API, portal sharing, ingress controller, and so on).

Values: SDS | ArcObjects11 | DMaps | Undefined | Postgres | Tiles | Ignite | MinIO | Elasticsearch | RabbitMQ | ArcObjectsRasterRendering

id

The template ID.

Example

"id": "9375dd81-30d1-41c0-a802-cabb425159a9",
type

The microservice type. For example, if the microservice is a shared feature server containing feature services, FeatureServer is returned. For microservices that are not service related, System is returned.

Values: FeatureServer | GeometryServer | GPServer | GPSyncServer | MapServer | TileServer | System | InMemoryStore | ObjectStore | SpatiotemporalIndexStore | QueueServer | RelationalStore | WebhookProcessor (Added at 11.0)

spec

The JSON object representation of the template's specifications, including replicas and container resources.

Example


"spec": {
  "replicas": {
    "min": 3,
    "max": 3,
    "scalingMode": "manual" //Added at 11.0
  },
  "containers": [
    {
      "name": "main-container",
      "resources": {
        "memoryMin": "1.5Gi",
        "memoryMax": "4Gi",
        "cpuMin": "0.125",
        "cpuMax": "2"
      },
      "containerImageKey": "GP_SERVER"
    },
    {
      "name": "filebeat",
      "resources": {
        "memoryMin": "32Mi",
        "memoryMax": "50Mi",
        "cpuMin": "0.05",
        "cpuMax": "0.25"
      },
      "containerImageKey": "FILEBEAT"
    }
  ]
},
revision

The date, in milliseconds from epoch format, of the latest revision to the template.

Example

"revision": 1598217421474

Example usage

Caution:

Though both the scaling and placement policy for a deployment can be updated using the Edit (Deployment) and Edit (Default Properties) operations, to reduce risk of errors it is recommended that changes to these properties are performed at the service-level for currently configured services. For scaling, see the Edit (Scaling) operation. For placement policies, see the Edit (Placement Policy) operation.

The following is a sample POST request for the edit operation that demonstrates autoscaling, formatted for readability:


POST /context/admin/system/deployments/d23ae35d2-e81a-4e79-93de-90fcf1388908/edit HTTP/1.1
Host: organization.domain.com
Content-Type: application/x-www-form-urlencoded
Content-Length: []

deploymentJson={
  "mode": "Primary",
  "configuredState": "STARTED",
  "provider": "Postgres",
  "deploymentId": "ke84ls9uva6t7fvck8q5p",
  "name": "relational-store-primary",
  "type": "RelationalStore",
  "spec": {
    "replicas": {
      "min": 1,
      "max": 10,
      "scalingMode": "auto",
      "autoscaling": {
        "hpaSpec": {
          "metrics": [
            {
              "resource": {
                "name": "cpu",
                "target": {
                  "averageUtilization": "65",
                  "type": "Utilization"
                }
              },
              "type": "Resource"
            }
          ],
          "hpaVersion": "autoscaling/v2"
        }
      }
    },
    "containers": [
      {
        "name": "filebeat",
        "resources": {
          "memoryMin": "32Mi",
          "memoryMax": "50Mi",
          "cpuMin": "0.05",
          "cpuMax": "0.25"
        },
        "containerImageUrl": "container.image.com/info:1082",
        "containerImageKey": "FILEBEAT"
      },
      {
        "name": "main-container",
        "resources": {
          "memoryMin": "2Gi",
          "memoryMax": "8Gi",
          "cpuMin": "0.5",
          "cpuMax": "4"
        },
        "containerImageUrl": "container.image.com/info:1082",
        "containerImageKey": "STORE_POSTGRES"
      }
    ]
  },
  "labels": {},
  "revision": 1618223097333
}&f=pjson&token=B4SGXu8PifZbfOJxpbr-i3X66FvpOuDtp4UdaBqmodRHAxxI-El280UH26TsC9YBct-6TJ_6wYH8iJB39SCwJIB6Vl8_DXmhvROZxjWMk_boLq6J-hurAvVdsOwYLlE7uy7j5t7lpQBAOqvnXS1lxGCy1vwnr3OPLoKmOWY8S8dxP1ZNrRx_SlTSfshlnMP7yoYIArLIylO0Gga9gcyDa3DYsDeTKU8uKbkUQ6LEwo93g1cU9zAxFnxhlBdHw-9U

JSON Response examples

If async is false, the following response is returned:

{"status": "success"}

If async is true, the following response is returned. The value returned for jobsUrl can be used to access the job resource to track a job's status after it's been submitted. For more information, see the Job resource topic.


{
  "jobsUrl": "https://organization.domain.com/context/admin/jobs/ja2ca1a35-881c-400c-a49a-b26883002d6c",
  "jobID": "ja2ca1a35-881c-400c-a49a-b26883002d6c",
  "jobStatus": "SUBMITTED"
}