--- title: "POST /v2/{+parent}/policyOrchestrators" method: POST path: "/v2/{+parent}/policyOrchestrators" tags: ["folders"] --- # POST /v2/{+parent}/policyOrchestrators `POST /v2/{+parent}/policyOrchestrators` Creates a new policy orchestrator under the given folder resource. `name` field of the given orchestrator are ignored and instead replaced by a product of `parent` and `policy_orchestrator_id`. Orchestrator state field might be only set to `ACTIVE`, `STOPPED` or omitted (in which case, the created resource will be in `ACTIVE` state anyway). ## Path parameters - `parent` string, required ## Query parameters - `policyOrchestratorId` string - `requestId` string ## Request body - GoogleCloudOsconfigV2PolicyOrchestrator — A policy orchestrator manages project-level and zone-level policy resources, such as OS policy assignments. It provides methods to create, update, and delete these resources across projects and locations at scale. The policy orchestrator operates as a continuous loop. In each iteration, the orchestrator identifies the set of resources to be modified and progressively applies changes. If the set of resources changes over time (for example, if you add new projects), subsequent iterations address those changes. The orchestrator can either upsert or delete policy resources. For more details, see the `action` and `orchestrated_resource` fields. The policy orchestrator does not manage the lifecycle of the resources it creates. Each iteration is independent and, besides Cloud Logging, the orchestrator retains only a minimal history of past actions. Deleting the orchestrator does not affect previously created resources; these resources remain in their current state. Similarly, removing projects from the orchestrator's scope does not affect existing resources. - `orchestrationScope` GoogleCloudOsconfigV2OrchestrationScope — Defines a set of selectors which drive which resources are in scope of policy orchestration. - `selectors` GoogleCloudOsconfigV2OrchestrationScopeSelector[] — 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. - `resourceHierarchySelector` GoogleCloudOsconfigV2OrchestrationScopeResourceHierarchySelector — Selector containing Cloud Resource Manager resource hierarchy nodes. - `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` GoogleCloudOsconfigV2OrchestrationScopeLocationSelector — Selector containing locations in scope. - `includedLocations` string[] — Optional. Names of the locations in scope. Format: `us-central1-a` - `action` string — Required. Action to be done by the orchestrator in `projects/{project_id}/zones/{zone_id}` locations defined by the `orchestration_scope`. Allowed values: - `UPSERT` - Orchestrator will create or update target resources. - `DELETE` - Orchestrator will delete target resources, if they exist - `name` string — Immutable. Identifier. In the following format: * `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}` - `createTime` string, google-datetime — Output only. Timestamp when the policy orchestrator resource was created. - `description` string — Optional. Freeform text describing the purpose of the resource. - `orchestrationState` GoogleCloudOsconfigV2PolicyOrchestratorOrchestrationState — Describes the state of the orchestration process. - `currentIterationState` GoogleCloudOsconfigV2PolicyOrchestratorIterationState — Describes the state of a single iteration of the orchestrator. - `state` 'STATE_UNSPECIFIED' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'UNKNOWN' — Output only. State of the iteration. - `error` Status — The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `message` string — A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `details` object[] — A list of messages that carry the error details. There is a common set of message types for APIs to use. - `code` integer — The status code, which should be an enum value of google.rpc.Code. - `startTime` string, google-datetime — Output only. Start time of the wave iteration. - `performedActions` string, int64 — Output only. Overall number of actions done by the orchestrator so far. - `failedActions` string, int64 — Output only. Number of orchestration actions which failed so far. For more details, query the Cloud Logs. - `iterationId` string — Output only. Unique identifier of the iteration. - `finishTime` string, google-datetime — Output only. Finish time of the wave iteration. - `progress` number, float — Output only. An estimated percentage of the progress. Number between 0 and 100. - `previousIterationState` GoogleCloudOsconfigV2PolicyOrchestratorIterationState — Describes the state of a single iteration of the orchestrator. - `state` 'STATE_UNSPECIFIED' | 'PROCESSING' | 'COMPLETED' | 'FAILED' | 'CANCELLED' | 'UNKNOWN' — Output only. State of the iteration. - `error` Status — The `Status` type defines a logical error model that is suitable for different programming environments, including REST APIs and RPC APIs. It is used by [gRPC](https://github.com/grpc). Each `Status` message contains three pieces of data: error code, error message, and error details. You can find out more about this error model and how to work with it in the [API Design Guide](https://cloud.google.com/apis/design/errors). - `message` string — A developer-facing error message, which should be in English. Any user-facing error message should be localized and sent in the google.rpc.Status.details field, or localized by the client. - `details` object[] — A list of messages that carry the error details. There is a common set of message types for APIs to use. - `code` integer — The status code, which should be an enum value of google.rpc.Code. - `startTime` string, google-datetime — Output only. Start time of the wave iteration. - `performedActions` string, int64 — Output only. Overall number of actions done by the orchestrator so far. - `failedActions` string, int64 — Output only. Number of orchestration actions which failed so far. For more details, query the Cloud Logs. - `iterationId` string — Output only. Unique identifier of the iteration. - `finishTime` string, google-datetime — Output only. Finish time of the wave iteration. - `progress` number, float — Output only. An estimated percentage of the progress. Number between 0 and 100. - `updateTime` string, google-datetime — Output only. Timestamp when the policy orchestrator resource was last modified. - `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. - `labels` object — Optional. Labels as key value pairs - `reconciling` boolean — Output only. Set to true, if there are ongoing changes being applied by the orchestrator. - `orchestratedResource` GoogleCloudOsconfigV2OrchestratedResource — Represents a resource that is being orchestrated by the policy orchestrator. - `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. - `osPolicyAssignmentV1Payload` OSPolicyAssignment — OS policy assignment is an API resource that is used to apply a set of OS policies to a dynamically targeted group of Compute Engine VM instances. An OS policy is used to define the desired state configuration for a Compute Engine VM instance through a set of configuration resources that provide capabilities such as installing or removing software packages, or executing a script. For more information about the OS policy resource definitions and examples, see [OS policy and OS policy assignment](https://cloud.google.com/compute/docs/os-configuration-management/working-with-os-policies). - `revisionId` string — Output only. The assignment revision ID A new revision is committed whenever a rollout is triggered for a OS policy assignment - `osPolicies` OSPolicy[] — Required. List of OS policies to be applied to the VMs. - `description` string — Policy description. Length of the description is limited to 1024 characters. - `allowNoResourceGroupMatch` boolean — This flag determines the OS policy compliance status when none of the resource groups within the policy are applicable for a VM. Set this value to `true` if the policy needs to be reported as compliant even if the policy has nothing to validate or enforce. - `resourceGroups` OSPolicyResourceGroup[] — Required. List of resource groups for the policy. For a particular VM, resource groups are evaluated in the order specified and the first resource group that is applicable is selected and the rest are ignored. If none of the resource groups are applicable for a VM, the VM is considered to be non-compliant w.r.t this policy. This behavior can be toggled by the flag `allow_no_resource_group_match` - `resources` OSPolicyResource[] — Required. List of resources configured for this resource group. The resources are executed in the exact order specified here. - `pkg` OSPolicyResourcePackageResource — A resource that manages a system package. - … - `file` OSPolicyResourceFileResource — A resource that manages the state of a file. - … - `repository` OSPolicyResourceRepositoryResource — A resource that manages a package repository. - … - `exec` OSPolicyResourceExecResource — A resource that allows executing scripts on the VM. The `ExecResource` has 2 stages: `validate` and `enforce` and both stages accept a script as an argument to execute. When the `ExecResource` is applied by the agent, it first executes the script in the `validate` stage. The `validate` stage can signal that the `ExecResource` is already in the desired state by returning an exit code of `100`. If the `ExecResource` is not in the desired state, it should return an exit code of `101`. Any other exit code returned by this stage is considered an error. If the `ExecResource` is not in the desired state based on the exit code from the `validate` stage, the agent proceeds to execute the script from the `enforce` stage. If the `ExecResource` is already in the desired state, the `enforce` stage will not be run. Similar to `validate` stage, the `enforce` stage should return an exit code of `100` to indicate that the resource in now in its desired state. Any other exit code is considered an error. NOTE: An exit code of `100` was chosen over `0` (and `101` vs `1`) to have an explicit indicator of `in desired state`, `not in desired state` and errors. Because, for example, Powershell will always return an exit code of `0` unless an `exit` statement is provided in the script. So, for reasons of consistency and being explicit, exit codes `100` and `101` were chosen. - … - `id` string — Required. The id of the resource with the following 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 OS policy. - `inventoryFilters` OSPolicyInventoryFilter[] — List of inventory filters for the resource group. The resources in this resource group are applied to the target VM if it satisfies at least one of the following inventory filters. For example, to apply this resource group to VMs running either `RHEL` or `CentOS` operating systems, specify 2 items for the list with following values: inventory_filters[0].os_short_name='rhel' and inventory_filters[1].os_short_name='centos' If the list is empty, this resource group will be applied to the target VM unconditionally. - `osShortName` string — Required. The OS short name - `osVersion` string — The OS version Prefix matches are supported if asterisk(*) is provided as the last character. For example, to match all versions with a major version of `7`, specify the following value for this field `7.*` An empty string matches all OS versions. - `id` string — Required. The id of the OS policy with the following 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 assignment. - `mode` 'MODE_UNSPECIFIED' | 'VALIDATION' | 'ENFORCEMENT' — Required. Policy mode - `uid` string — Output only. Server generated unique id for the OS policy assignment resource. - `etag` string — The etag for this OS policy assignment. If this is provided on update, it must match the server's etag. - `baseline` boolean — Output only. Indicates that this revision has been successfully rolled out in this zone and new VMs will be assigned OS policies from this revision. For a given OS policy assignment, there is only one revision with a value of `true` for this field. - `name` string — Resource name. Format: `projects/{project_number}/locations/{location}/osPolicyAssignments/{os_policy_assignment_id}` This field is ignored when you create an OS policy assignment. - `rollout` OSPolicyAssignmentRollout — Message to configure the rollout at the zonal level for the OS policy assignment. - `disruptionBudget` FixedOrPercent — Message encapsulating a value that can be either absolute ("fixed") or relative ("percent") to a value. - `fixed` integer — Specifies a fixed value. - `percent` integer — Specifies the relative value defined as a percentage, which will be multiplied by a reference value. - `minWaitDuration` string, google-duration — Required. This determines the minimum duration of time to wait after the configuration changes are applied through the current rollout. A VM continues to count towards the `disruption_budget` at least until this duration of time has passed after configuration changes are applied. - `deleted` boolean — Output only. Indicates that this revision deletes the OS policy assignment. - `reconciling` boolean — Output only. Indicates that reconciliation is in progress for the revision. This value is `true` when the `rollout_state` is one of: * IN_PROGRESS * CANCELLING - `instanceFilter` OSPolicyAssignmentInstanceFilter — Filters to select target VMs for an assignment. If more than one filter criteria is specified below, a VM will be selected if and only if it satisfies all of them. - `all` boolean — Target all VMs in the project. If true, no other criteria is permitted. - `inventories` OSPolicyAssignmentInstanceFilterInventory[] — List of inventories to select VMs. A VM is selected if its inventory data matches at least one of the following inventories. - `osShortName` string — Required. The OS short name - `osVersion` string — The OS version Prefix matches are supported if asterisk(*) is provided as the last character. For example, to match all versions with a major version of `7`, specify the following value for this field `7.*` An empty string matches all OS versions. - `inclusionLabels` OSPolicyAssignmentLabelSet[] — List of label sets used for VM inclusion. If the list has more than one `LabelSet`, the VM is included if any of the label sets are applicable for the VM. - `labels` object — Labels are identified by key/value pairs in this map. A VM should contain all the key/value pairs specified in this map to be selected. - `exclusionLabels` OSPolicyAssignmentLabelSet[] — List of label sets used for VM exclusion. If the list has more than one label set, the VM is excluded if any of the label sets are applicable for the VM. - `labels` object — Labels are identified by key/value pairs in this map. A VM should contain all the key/value pairs specified in this map to be selected. - `revisionCreateTime` string, google-datetime — Output only. The timestamp that the revision was created. - `description` string — OS policy assignment description. Length of the description is limited to 1024 characters. - `rolloutState` 'ROLLOUT_STATE_UNSPECIFIED' | 'IN_PROGRESS' | 'CANCELLING' | 'CANCELLED' | 'SUCCEEDED' — Output only. OS policy assignment rollout state - `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. ## Response `200` Successful response --- [API](https://skmtc.dev/google/apis/osconfig.md) · [All operations](https://skmtc.dev/google/apis/osconfig/llms.txt) · [OpenAPI document](https://skmtc-service-production.skmtc.workers.dev/v1/apis/google/osconfig/revisions/ae877719e00c/schema)