REST Resource: folders.locations.global.policyOrchestrators

Resource: PolicyOrchestrator

PolicyOrchestrator helps managing project+zone level policy resources (e.g. OS Policy Assignments), by providing tools to create, update and delete them across projects and locations, at scale.

Policy orchestrator functions as an endless loop. Each iteration orchestrator computes a set of resources that should be affected, then progressively applies changes to them. If for some reason this set of resources changes over time (e.g. new projects are added), the future loop iterations will address that.

Orchestrator can either upsert or delete policy resources. For more details, see the description of the action, and orchestratedResource fields.

Note that policy orchestrator do not "manage" the resources it creates. Every iteration is independent and only minimal history of past actions is retained (apart from Cloud Logging). If orchestrator gets deleted, it does not affect the resources it created in the past. Those will remain where they were. Same applies if projects are removed from the orchestrator's scope.

JSON representation 
{
  "name": string,
  "description": string,
  "etag": string,
  "state": string,
  "reconciling": boolean,
  "orchestrationScope": {
    object (OrchestrationScope)
  },
  "action": string,
  "orchestratedResource": {
    object (OrchestratedResource)
  },
  "orchestrationState": {
    object (OrchestrationState)
  },
  "createTime": string,
  "updateTime": string,
  "labels": {
    string: string,
    ...
  }
}
Fields
name

string

Immutable. Identifier. In form of * organizations/{organization_id}/locations/global/policyOrchestrators/{orchestrator_id} * folders/{folder_id}/locations/global/policyOrchestrators/{orchestrator_id} * projects/{project_id_or_number}/locations/global/policyOrchestrators/{orchestrator_id}
description

string

Optional. Freeform text describing the purpose of the resource.
etag

string

Output only. This checksum is computed by the server based on the value of other fields, and may be sent on update and delete requests to ensure the client has an up-to-date value before proceeding.
state

string

Optional. State of the orchestrator. Can be updated to change orchestrator behaviour. Allowed values: - ACTIVE - orchestrator is actively looking for actions to be taken. - STOPPED - orchestrator won't make any changes.

Note: There might be more states added in the future. We use string here instead of an enum, to avoid the need of propagating new states to all the client code.
reconciling

boolean

Output only. Set to true, if the there are ongoing changes being applied by the orchestrator.
orchestrationScope

object (OrchestrationScope)

Optional. Defines scope for the orchestration, in context of the enclosing PolicyOrchestrator resource.

Scope is expanded into a list of <project, zone> pairs, in which the rollout action will take place. Expansion starts with a Folder resource parenting the PolicyOrchestrator resource: - All the descendant projects are listed. - List of project is cross joined with a list of all available zones. - Resulting list of <project, zone> pairs is filtered according to the selectors.
action

string

Required. Action to be done by the orchestrator in projects/{projectId}/zones/{zone_id} locations defined by the orchestrationScope. Allowed values: - UPSERT - Orchestrator will create or update target resources. - DELETE - Orchestrator will delete target resources, if they exist
orchestratedResource

object (OrchestratedResource)

Required. Resource to be orchestrated by the policy orchestrator.
orchestrationState

object (OrchestrationState)

Output only. State of the orchestration.
createTime

string (Timestamp format)

Output only. Timestamp when the policy orchestrator resource was created.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
updateTime

string (Timestamp format)

Output only. Timestamp when the policy orchestrator resource was last modified.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
labels

map (key: string, value: string)

Optional. Labels as key value pairs

An object containing a list of "key": value pairs. Example: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

OrchestrationScope

Defines a set of selectors which drive which resources are in scope of policy orchestration.

JSON representation 
{
  "selectors": [
    {
      object (Selector)
    }
  ]
}
Fields
selectors[]

object (Selector)

Optional. Selectors of the orchestration scope. There is a logical AND between each selector defined.

When there is no explicit ResourceHierarchySelector selector specified, the scope is by default bounded to the parent of the policy orchestrator resource.

Selector

Selector for the resources in scope of orchestration.

JSON representation 
{

  // Union field selector_type can be only one of the following:
  "resourceHierarchySelector": {
    object (ResourceHierarchySelector)
  },
  "locationSelector": {
    object (LocationSelector)
  }
  // End of list of possible types for union field selector_type.
}
Fields
Union field selector_type. Type of Selector to be used for rollouts. selector_type can be only one of the following:
resourceHierarchySelector

object (ResourceHierarchySelector)

Selector for selecting resource hierarchy.
locationSelector

object (LocationSelector)

Selector for selecting locations.

ResourceHierarchySelector

Selector containing Cloud Resource Manager resource hierarchy nodes.

JSON representation 
{
  "includedProjects": [
    string
  ],
  "includedFolders": [
    string
  ]
}
Fields
includedProjects[]

string

Optional. Names of the projects in scope. Format: projects/{project_number}
includedFolders[]

string

Optional. Names of the folders in scope. Format: folders/{folder_id}

LocationSelector

Selector containing locations in scope.

JSON representation 
{
  "includedLocations": [
    string
  ]
}
Fields
includedLocations[]

string

Optional. Names of the locations in scope. Format: us-central1-a

OrchestratedResource

Represents a resource that is being orchestrated by the policy orchestrator.

JSON representation 
{
  "id": string,

  // Union field payload can be only one of the following:
  "osPolicyAssignmentV1Payload": {
    object (OSPolicyAssignment)
  }
  // End of list of possible types for union field payload.
}
Fields
id

string

Optional. ID of the resource to be used while generating set of affected resources.

For UPSERT action the value is auto-generated during PolicyOrchestrator creation when not set. When the value is set it should following next restrictions:

  • Must contain only lowercase letters, numbers, and hyphens.
  • Must start with a letter.
  • Must be between 1-63 characters.
  • Must end with a number or a letter.
  • Must be unique within the project.

For DELETE action, ID must be specified explicitly during PolicyOrchestrator creation.

Union field payload. For UPSERT action, payload represents a type and content of the resource that will be created/updated for a particular <project, zone> pair from orchestration scope.

For DELETE action, a payload must be set to indicate type of the resource that will be deleted. It can be either: - an empty message, - a correct resource content. payload can be only one of the following:
osPolicyAssignmentV1Payload

object (OSPolicyAssignment)

Optional. OSPolicyAssignment resource to be created, updated or deleted. Name field is ignored and replace with a generated value.

With this field set, orchestrator will perform actions on project/{project}/locations/{zone}/osPolicyAssignments/{resource_id} resources, where project and zone pairs come from the expanded scope, and resource_id comes from the resource_id field of orchestrator resource.

OrchestrationState

Describes the state of the orchestration process.

JSON representation 
{
  "currentIterationState": {
    object (IterationState)
  },
  "previousIterationState": {
    object (IterationState)
  }
}
Fields
currentIterationState

object (IterationState)

Output only. Current Wave iteration state.
previousIterationState

object (IterationState)

Output only. Previous Wave iteration state.

IterationState

Describes the state of a single iteration of the orchestrator.

JSON representation 
{
  "state": enum (State),
  "rolloutResource": string,
  "progress": number,
  "performedActions": string,
  "failedActions": string,
  "startTime": string,
  "finishTime": string,
  "error": {
    object (Status)
  }
}
Fields
state

enum (State)

Output only. State of the iteration.
rolloutResource

string

Output only. Handle to the Progressive Rollouts API rollout resource, which contains detailed information about a particular orchestration iteration.
progress

number

Output only. An estimated percentage of the progress. Number between 0 and 100.
performedActions

string (int64 format)

Output only. Overall number of actions done by the orchestrator so far.
failedActions

string (int64 format)

Output only. Number of orchestration actions which failed so far. For more details, query the Cloud Logs.
startTime

string (Timestamp format)

Output only. Start time of the wave iteration.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
finishTime

string (Timestamp format)

Output only. Finish time of the wave iteration.

A timestamp in RFC3339 UTC "Zulu" format, with nanosecond resolution and up to nine fractional digits. Examples: "2014-10-02T15:01:23Z" and "2014-10-02T15:01:23.045123456Z".
error

object (Status)

Output only. Error thrown in the wave iteration.

State

Possible states of the iteration.

Enums
STATE_UNSPECIFIED Default value. This value is unused.
PROCESSING Iteration is in progress.
COMPLETED Iteration completed, with all actions being successful.
FAILED Iteration completed, with failures.
CANCELLED Iteration was explicitly cancelled.
UNKNOWN Impossible to determine current state of the iteration.

Methods

create

 Creates a new policy orchestrator under the given folder resource.

delete

 Deletes an existing policy orchestrator resource, parented by a folder.

get

 Retrieves an existing policy orchestrator, parented by a folder.

list

 Lists the policy orchestrators under the given parent folder resource.

patch

 Updates an existing policy orchestrator, parented by a folder.