Granting Policy Permissions

This section lists and describes the policy permissions available for each resource type. Policy permission on a resource type is the combination of a consequent claim type and value issued by the policy engine. See Policy Syntax for reference.

Audit permissions

Policy permissions on resources in the audit::/ realm to grant users read-only access to the audit log. The audit log is visible in the web console.

The following claim is applicable to the audit::/ realm and all descendant realms.

Claim Type Claim Value Description
permit read Signals the API server that the requester of the operation can read the audit log.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

See Audit Policy Examples for guidance.

Auth permissions

All claim types are asserted by the policy engine, except for claim types on the auth::/ realm and its descendants. Claim types on the auth::/ realm are issued by an authority such as the Auth Server or an identity provider such as Google Auth.

Realm auth::/

Policy permission on the auth::/ realm let you establish default namespaces for users of the system.

The following table summarizes the claim and type available for the auth::/ realm.

Claim Type Claim Value Description
defaultNamespace <FQN> Sets default namespace to the specified FQN.
defaultNamespacePrefix user-defined string Sets the namespace prefix to the claim value.

The defaultNamespace and defaultNamespacePrefix claim types are issued by the Auth Server (auth_server@apcera.me).

If neither claim tyupe is defined for a user then the default cluster behavior is to use /sandbox/<principal-name>. For example, if a user authenticates as bob_jones@gmail.com, the user is put into the /sandbox/bob_jones. If the user authenticates using LDAP then the ldap_basic auth server can be configured to provide a relativeNamespace user claim to be used as the principal-name.

Refer to Default Namespace Policy Examples for guidance.

Realm auth::/ldap

Policy permissions on the auth::/ldap realm controls LDAP interactions, specifically for LDAP groups.

The following table summarizes the claim and type available for the auth::/ldap realm.

Claim Type Claim Value Description
group.allow Comma-separated list of quoted values You must explicitly reference the group(s) to be queried by the LDAP server. To discourage blank check whitelisting, the wildcard asterisk character (*) is allowed only as part of a pattern; using group.allow "*" is not allowed. See example below.

For example, the group.allow claim type is defined in auth::/ldap namespace with the following group names.

auth::/ldap {
   { group.allow "group1", "dev-*", "ops" }
}

Note that Group names are pulled from both the cluster.conf and the group.allow claim on the auth::/ldap namespace. There is no precedence rule and both sources are taken into account. Using the group.allow claim gives you flexibility over the statically-defined settings in the cluster.conf file. Note also that you can whitelist groups via "groups" : "*" in the cluser.conf. See Using LDAP as the identity provider for details.

Realm auth::/oauth2/http

Policy permissions on the auth::/oauth2/http realm controls auth token issuance for HTTP endpoints.

The following table summarizes the claims and types available for the auth::/oauth2/http realm.

Claim Type Claim Value Description
email somevalue Permits token issuance to when the identity provider asserts the requester has the authenticated email address.
permit issue Signals Auth Server to issue a token to the requester.
name somevalue Sets the subject of the auth token; usually a name or email address, but any string value is acceptable.
tokenTimeout in seconds Sets the token timeout; default is 24 hours ("86400s").

Claim types name and permit are issued by the Auth Server (auth_server@apcera.me). Claim type email is issued by an external authority, such as Google Auth (google). See Policy Syntax for details.

See Auth Policy Examples for guidance.

Realm auth::/oauth2/nats

The auth::/oauth2/nats realm is used by system components to access NATS messages. This realm is reserved for internal use.

Cluster permissions

Policy permissions on resources in the cluster::/ realm let authorized read metrics on cluster resources. By default, this policy gives valid requestors the ability to read metrics on cluster resources and potentially to modify attributes of cluster configuration.

Claim Type Claim Value Description
permit read Grants permission to view cluster details.
permit update Grants permission to update cluster details. (This claim type is reserved for future use.)
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

Refer to the Cluster Policy Example for guidance.

Gateway permissions

Policy permissions on resources in the gateway::/ realm let authorized users use service gateways and promote jobs to service gateways.

The following is a list of consequents applicable to the gateway::/ realm and all subordinate realms.

Claim Type Claim Value Description
permit promote Grants permission to promote a job to a service gateway.
permit use Grants permission to use the gateway to create a service.
log none Do not generate policy.access.allowed or policy.access.denied access audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

To promote a job to a gateway, there must be permit promote claim on both the gateway resource and the job resource.

See Service Gateway Policy Example for guidance.

Job permissions

You apply policy on resources in the job::/ realm and its descendants to control the creation, management, and connectivity of jobs in the cluster. Jobs in this context means user-defined workloads, including apps, capsules, and Docker images.

The following table lists the claims applicable to the job::/ realm and all subordinate realms.

Claim Type Claim Value Description
permit bind Bind the job to a given service with an FQN matching service
permit create Create a new job.
permit delete Delete the job.
permit link Link the source job to destination job.
permit join Join the source job to a virtual network.
permit map Map the route and job.
permit promote Promote the job to a gateway with an FQN matching gateway.
permit read Read all aspects of the job and see the job in job list.
permit ssh Connect to the job container via SSH.
permit start Start the job.
permit stop Stop the job.
permit update Update any part of the job.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

A user can be granted permission to start or stop a job with permit start and permit stop, respectively. Any other job modification requires permit update. Authorization to link, bind, map, and promote jobs are two-way handshakes requiring policy on both the source job and the target resource.

See Job Policy Examples for guidance.

There are additional claims available on the job::/ realm for Docker jobs and package resolution for jobs. See below.

Docker claim for jobs

Docker images run as jobs in the system. You apply policy on resources in the job::/ realm to allow Docker image pulls.

The following claim is specific to Docker images:

Claim Type Claim Value Description
docker.allow Docker Hub URL Whitelist Docker Hub images.

The above claim is enforced on resources in the job::/ realm and its descendants. Note that this is a separate claim and must be declared on its own line. For example:

on job::/sandbox/NAME {
  if (role == "NAME")
  {
    docker.allow "*"
    permit create, read, update, delete
  }
}

See Docker Policy Examples for guidance.

Package resolution claims for jobs

You apply policy on resources in the job::/ realm to control package resolution.

The following table lists and describes the claims applicable to the job::/ realm and its descendants for package resolution.

Claim Type Claim Value Description
package.allow <package_FQN> FQN of a package that is allowed to be used by the job.
package.default <package_FQN> FQN of a package that can fulfill a dependency, in absence of any overrides.
package.lock <package_FQN> FQN of a package that must be used to fulfill a dependency.
package.retire <package_FQN> FQN of a package that cannot be used by the job.

The above claims are package-level permissions that are enforced on resources in the job::/ realm and its descendants.

See Package Resolution Policy Examples for guidance.

Network permissions

You apply policy on resources in the network::/ realm to control access to virtual networks. The following table lists the permissions applicable to the network::/ realm and all descendant realms.

To permit a job to join a virtual network there must be a permit join claim on both the job and the network resource.

Claim Type Claim Value Description
permit create Create a new virtual network.
permit delete Delete the virtual network.
permit join Join the virtual network to a job.
permit read Read all aspects of the virtual network and list the network in apc network list.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

See Network Policy Examples for guidance.

Package permissions

You apply policy on resources in the package::/ realm to control access to packages, including operating systems (os), runtimes, and other package dependencies (packages).

The following table lists the permissions applicable to the package::/ realm and all descendant realms.

Claim Type Claim Value Description
permit create Create a new package.
permit read Read all aspects of the package and see the package in package list.
permit update Update any part of the package.
permit delete Delete the package.
permit use Job with a given FQN (job) can depend on the package.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

Refer to Package Policy Examples for guidance on writing policy on package resources.

Policy authoring permissions

You apply policy on resources in the policy::/ realm to govern access to policies in the system.

Apcera Platform uses policy to control operations on the Policy API ("policy on policy"). This lets you delegate policy controls to others and define limits on the types of policy operations the delegated requester can perform.

The following table lists and describes the consequent claims applicable to the policy::/ realm and its descendants.

Claim Type Claim Value Description
permit read Read the contents of a realm.
permit update Update the contents of a realm.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

The following table lists and describes the antecedent claims applicable to the policy::/ realm and its descendants.

Claim Type Claim Value Description
ResType audit Read or update policy on audit::/ realms.
ResType auth Read or update policy on auth::/ realms
ResType cluster Read or update policy on cluster::/ realms
ResType gateway Read or update policy on gateway::/ realms
ResType job Read or update policy on job::/ realms
ResType package Read or update policy on package::/ realms
ResType policy Read or update policy on policy::/ realms
ResType policydoc Read or update policy on policydoc::/ realms
ResType provider Read or update policy on provider::/ realms
ResType quota Read or update policy on quota::/ realms
ResType route Read or update policy on route::/ realms
ResType sempiperule Read or update policy on sempiperule::/ realms
ResType service Read or update policy on service::/ realms
ResType stagpipe Read or update policy on stagpipe::/ realms

Permissions on policy::/ let you view (read) and edit/create (update) policy, assuming you have resType permissions on all resources identified by the realms in the policy document.

See Policy on Policy Examples for examples.

Policy administration permissions

You can apply policy on resources in the policydoc::/ realm to control creation and deletion of policy documents.

The following table lists and describes the claims applicable to the policydoc::/ realm and its descendants.

Claim Type Claim Value Description
permit create Create a policy document.
permit read Read a policy document.
permit update Update a policy document.
permit delete Delete a policy document.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

CRUD permissions on resources in the policydoc::/ realm let a user create individual policy documents absent permissions on the policy::/ realm.

See Policy on Policy Examples for guidance.

Provider permissions

Policy permissions on resources in the provider::/ realm and its descendants to control access to providers, such as a database server.

The following table contains a list of consequents applicable to provider::/ realm and descendant realms.

Claim Type Claim Value Description
permit create Permission to create a provider.
permit read Permission to read all aspects of the provider and see the provider in provider list.
permit update Permission to update a provider.
permit delete Permission to delete a provider.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

See Provider Policy Examples for guidance.

Quota permissions

Policy permissions on resources in the quota::/ realm control the amount of computing resources jobs and packages can consume.

The following table lists and describes the claims applicable to the quota::/ realm and descendant realms.

Claim Type Claim Value Description
max.job.cpu Int64 Maximum CPU time (in milliseconds per second) that can be used by a job in the namespace.
max.instance.cpu Int64 Maximum CPU time that can be used by a single instance of a job in the namespace.
total.cpu Int64 Total CPU time for all job instances in a namespace.
max.job.memory ByteSize Maximum memory size for all instances of a job in the namespace.
max.instance.memory ByteSize Maximum memory size of a single instance of a job in the namespace.
total.memory ByteSize Total memory size for all jobs in a namespace.
max.job.disk ByteSize Maximum disk size for all instances of a job in the namespace.
max.instance.disk ByteSize Maximum disk size for a single instance of a job in the namespace.
total.disk ByteSize Total disk size for all job instances in a namespace.
max.job.network BitrateSize Maximum network rate for all instances of a job in the namespace.
max.instance.network BitrateSize Maximum network rate for a single instance of a job in the namespace.
total.network BitrateSize Total network rate for all job instances in a namespace.
max.package.size ByteSize Maximum size for a single package.
total.package.size ByteSize Total size of all packages in the namespace.
max.packages Int64 Total package count in the namespace.
max.jobs Int64 Total job count in the namespace.
max.instances Int64 Total instance count in the namespace.

See Quota Policy Examples for guidance.

Route permissions

Policy permissions on resources in the route::/ realm and descendant realms control which routes you may assign to jobs.

The following consequent is applicable to the route::/ realm and all descendant realms.

Claim Type Claim Value Description
permit map Can map job and route.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

Policy permissions on job routes is a two-way handshake between the job and the route. There must be policy on both route::/ and job::/ resources.

See Routing Policy Examples for guidance.

Semantic pipeline permissions

Policy permissions on resources in the sempiperule::/ realm and its descendant realms let you control which users can use and create semantic pipeline rules.

The following table list and describes the claims types applicable to the sempiperule::/ realm and all descendant realms.

Claim Type Claim Value Description
permit create Create a new semantic pipeline rule.
permit read Read the configuration of a semantic pipeline rule.
permit delete Delete a semantic pipeline rule.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

See Semantic Pipeline Policy Examples for guidance.

Service permissions

Policy permissions on resources in the service::/ realm and its descendant realms let you control service use and creation.

The following table contains a list of consequents applicable to the service::/ realm and all descendant realms.

Claim Type Claim Value Description
permit create Create a new service.
permit read Read the configuration of a service.
permit update Update a service.
permit delete Delete a service.
permit bind Bind a job to the service.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

Permission to bind a job to a service is a two-way handshake requiring permissions on both the job and service realms.

See Service Policy Examples for guidance.

Staging permissions

The following table contains a list of consequents applicable to the stagpipe::/ realm and all descendant realms.

Claim Type Claim Value Description
permit create Create a new staging pipeline.
permit read Read the configuration of a staging pipeline.
permit update Update a staging pipeline.
permit delete Delete a staging pipeline.
permit use Use a staging pipeline for staging apps.
log none Do not generate policy.access.allowed or policy.access.denied audit log items for this realm or descendants.
log allow Generate policy.access.allowed audit log items for this realm and descendants.
log deny Generate policy.access.denied audit log items for this realm and descendants.

See Staging Policy Examples for guidance.