policies

Creates, updates, deletes, gets or lists a policies resource.

Overview

Name	policies
Type	Resource
Id	ovh.iam.policies

Fields

The following fields are returned by SELECT queries:

get

successful operation

Name	Datatype	Description
id	string (uuid)	Unique identifier of the policy
name	string	Name of the policy
conditions	object	Conditions restrict permissions following resources, date or customer's information
created_at	string (date-time)	Creation time (wire: createdAt)
description	string	Description of the policy
expired_at	string (date-time)	Expiration date of the policy, after this date it will no longer be applied (wire: expiredAt)
identities	array	Recipients of the delegated resources
owner	string	Owner of the policy
permissions	object	Permissions accorded to the recipients on the given resources
permissions_groups	array	Permissions groups accorded to the recipients on the given resources (wire: permissionsGroups)
read_only	boolean	Whether you can update policy (wire: readOnly)
resources	array	Resources to delegate
updated_at	string (date-time)	Last update time (wire: updatedAt)

list

Policy definition

Name	Datatype	Description
id	string (uuid)	Unique identifier of the policy
name	string	Name of the policy
conditions	object	Conditions restrict permissions following resources, date or customer's information
created_at	string (date-time)	Creation time (wire: createdAt)
description	string	Description of the policy
expired_at	string (date-time)	Expiration date of the policy, after this date it will no longer be applied (wire: expiredAt)
identities	array	Recipients of the delegated resources
owner	string	Owner of the policy
permissions	object	Permissions accorded to the recipients on the given resources
permissions_groups	array	Permissions groups accorded to the recipients on the given resources (wire: permissionsGroups)
read_only	boolean	Whether you can update policy (wire: readOnly)
resources	array	Resources to delegate
updated_at	string (date-time)	Last update time (wire: updatedAt)

Methods

The following methods are available for this resource:

Name	Accessible by	Required Params	Optional Params	Description
get	select	policy_id	details	Returns the policy definition. Set details to true to expand resource information.
list	select		x_pagination_cursor, x_pagination_size, action, details, identity, read_only, resource_urn	Returns the policies of the account. Filter with identity, resourceURN and action.<br />Set readOnly to true to include the read-only policies generated by OVHcloud.<br />Set details to true to expand resource information.
create	insert	identities, name, permissions, resources		Creates a policy that grants one or more identities access to a set of resources.<br /><br />identities are URNs: account (NIC), user (account-id/username) or group (account-id/group-name).<br />resources are resource or resourceGroup URNs.<br />Both actions and resource URNs may end with * to match several items at once.<br /><br />permissions.allow is the set of granted actions: everything else is denied by default.<br />permissions.except subtracts actions from that allow set (useful with wildcards).<br />permissions.deny forbids actions outright and always wins, including over allows from other policies.<br /><br />Optional permissionsGroups attach reusable allow/deny sets defined separately.<br />Optional conditions (AND / OR / NOT / MATCH over resource type, tags, name, request IP, date/time) must evaluate true for the policy to apply.<br />Optional expiredAt disables the policy after that date.<br /><br />A policy can target another OVHcloud account: the recipient can re-delegate only within the rights received, never beyond them.
update	update	policy_id, identities, name, permissions, resources		Updates the policy definition: identities, resources, permissions, conditions and expiry. Omitted optional fields keep their current value.
delete	delete	policy_id		Deletes the policy and the access it granted.

Parameters

Parameters can be passed in the WHERE clause of a query. Check the Methods section to see which parameters are required or optional for each operation.

Name	Datatype	Description
api_host	string	The OVHcloud API host. Selected by OVH_ENDPOINT (ovh-eu, ovh-ca or ovh-us; default ovh-eu). (default: api.eu.ovhcloud.com, x-stackQL-envVarSelector: {"envVar":"OVH_ENDPOINT","default":"ovh-eu","values":{"ovh-eu":"api.eu.ovhcloud.com","ovh-ca":"api.ca.ovhcloud.com","ovh-us":"api.us.ovhcloud.com"}})
policy_id	string (uuid)	Policy ID (wire: policyId)
action	array	Filter on policies embedding the given IAM action
details	boolean	Add extra information about resources in output
identity	array	Filter on policies embedding the given identity
read_only	boolean	Filter on the readOnly attribute (wire: readOnly)
resource_urn	array	Filter on policies embedding the given resource URN (wire: resourceURN)
x_pagination_cursor	string	Pagination cursor (wire: X-Pagination-Cursor)
x_pagination_size	integer	Pagination size (wire: X-Pagination-Size)

SELECT examples

get

Returns the policy definition. Set details to true to expand resource information.

SELECT
id,
name,
conditions,
created_at,
description,
expired_at,
identities,
owner,
permissions,
permissions_groups,
read_only,
resources,
updated_at
FROM ovh.iam.policies
WHERE policy_id = '{{ policy_id }}' -- required
AND details = '{{ details }}'
;

list

Returns the policies of the account. Filter with identity, resourceURN and action.<br />Set readOnly to true to include the read-only policies generated by OVHcloud.<br />Set details to true to expand resource information.

SELECT
id,
name,
conditions,
created_at,
description,
expired_at,
identities,
owner,
permissions,
permissions_groups,
read_only,
resources,
updated_at
FROM ovh.iam.policies
WHERE x_pagination_cursor = '{{ x_pagination_cursor }}'
AND x_pagination_size = '{{ x_pagination_size }}'
AND action = '{{ action }}'
AND details = '{{ details }}'
AND identity = '{{ identity }}'
AND read_only = '{{ read_only }}'
AND resource_urn = '{{ resource_urn }}'
;

INSERT examples

create

Creates a policy that grants one or more identities access to a set of resources.<br /><br />identities are URNs: account (NIC), user (account-id/username) or group (account-id/group-name).<br />resources are resource or resourceGroup URNs.<br />Both actions and resource URNs may end with * to match several items at once.<br /><br />permissions.allow is the set of granted actions: everything else is denied by default.<br />permissions.except subtracts actions from that allow set (useful with wildcards).<br />permissions.deny forbids actions outright and always wins, including over allows from other policies.<br /><br />Optional permissionsGroups attach reusable allow/deny sets defined separately.<br />Optional conditions (AND / OR / NOT / MATCH over resource type, tags, name, request IP, date/time) must evaluate true for the policy to apply.<br />Optional expiredAt disables the policy after that date.<br /><br />A policy can target another OVHcloud account: the recipient can re-delegate only within the rights received, never beyond them.

INSERT INTO ovh.iam.policies (
conditions,
description,
expired_at,
identities,
name,
permissions,
permissions_groups,
resources
)
SELECT 
'{{ conditions }}',
'{{ description }}',
'{{ expired_at }}',
'{{ identities }}' /* required */,
'{{ name }}' /* required */,
'{{ permissions }}' /* required */,
'{{ permissions_groups }}',
'{{ resources }}' /* required */
RETURNING
id,
name,
conditions,
created_at,
description,
expired_at,
identities,
owner,
permissions,
permissions_groups,
read_only,
resources,
updated_at
;

Manifest

# Description fields are for documentation purposes
- name: policies
props:
  - name: conditions
    description: |
      Conditions restrict permissions following resources, date or customer's information
    value:
      conditions:
        - conditions: "{{ conditions }}"
          operator: "{{ operator }}"
          values: "{{ values }}"
      operator: "{{ operator }}"
      values: "{{ values }}"
  - name: description
    value: "{{ description }}"
    description: |
      Description of the policy
  - name: expired_at
    value: "{{ expired_at }}"
    description: |
      Expiration date of the policy, after this date it will no longer be applied
  - name: identities
    value:
      - "{{ identities }}"
    description: |
      Recipients of the delegated resources
  - name: name
    value: "{{ name }}"
    description: |
      Name of the policy
  - name: permissions
    description: |
      Permissions accorded to the recipients on the given resources
    value:
      allow:
        - action: "{{ action }}"
      deny:
        - action: "{{ action }}"
      except:
        - action: "{{ action }}"
  - name: permissions_groups
    description: |
      Permissions groups accorded to the recipients on the given resources
    value:
      - name: "{{ name }}"
        owner: "{{ owner }}"
        permissions:
          allow:
            - action: "{{ action }}"
          deny:
            - action: "{{ action }}"
          except:
            - action: "{{ action }}"
        urn: "{{ urn }}"
  - name: resources
    description: |
      Resources to delegate
    value:
      - group:
          id: "{{ id }}"
          name: "{{ name }}"
          readOnly: {{ readOnly }}
        resource:
          displayName: "{{ displayName }}"
          id: "{{ id }}"
          name: "{{ name }}"
          owner: "{{ owner }}"
          tags: "{{ tags }}"
          type: "{{ type }}"
        urn: "{{ urn }}"

UPDATE examples

update

Updates the policy definition: identities, resources, permissions, conditions and expiry. Omitted optional fields keep their current value.

UPDATE ovh.iam.policies
SET 
conditions = '{{ conditions }}',
description = '{{ description }}',
expired_at = '{{ expired_at }}',
identities = '{{ identities }}',
name = '{{ name }}',
permissions = '{{ permissions }}',
permissions_groups = '{{ permissions_groups }}',
resources = '{{ resources }}'
WHERE 
policy_id = '{{ policy_id }}' --required
AND identities = '{{ identities }}' --required
AND name = '{{ name }}' --required
AND permissions = '{{ permissions }}' --required
AND resources = '{{ resources }}' --required
RETURNING
id,
name,
conditions,
created_at,
description,
expired_at,
identities,
owner,
permissions,
permissions_groups,
read_only,
resources,
updated_at;

DELETE examples

delete

Deletes the policy and the access it granted.

DELETE FROM ovh.iam.policies
WHERE policy_id = '{{ policy_id }}' --required
;