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 type 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.

Initial parameter claim for jobs

When creating a job instance, you can specify that the data volume on the job container to be encrypted using LUKS (Linux Unified Key Setup).
You apply policy on resources in the job::/ realm.

Claim Type	Claim Value	Description
initial.params	encrypt	Enforce the encryption of local (ephemeral) application data.

See Encryption at Rest Policy Examples for guidance.

Note that application data encryption can only be enforced using policy at job creation time, not on job update.

Job scheduling tag claims for jobs

You apply policy on resources in the job::/ realm to control the job deployment target.

The following table lists and describes the claims applicable to the job::/ realm for job scheduling.

Claim Type	Claim Value	Description
schedulingTag.hard	<IM_tag>	IM tag to specify where the jobs should run (hard requirement).
schedulingTag.soft	<IM_tag>	IM tag to specify where the jobs should run (soft requirement).
schedulingTag.hard	"~<IM_tag>"	IM tag to specify where not to run the jobs (hard requirement).
schedulingTag.soft	"~<IM_tag>"	IM tag to specify where not to run the jobs (soft requirement).

See Job Scheduling 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.

Scheduling tag claims for staging

You apply policy on the package::/ realm to control where to run the staging jobs during an app deploy or custom package build.

The following table lists and describes the claims applicable to the package::/ realm for tagging staging jobs.

Claim Type	Claim Value	Description
staging.schedulingTag.hard	<IM_tag>	IM tag to specify where the staging jobs should run (hard requirement).
staging.schedulingTag.soft	<IM_tag>	IM tag to specify where the staging jobs should run (soft requirement).
staging.schedulingTag.hard	"~<IM_tag>"	IM tag to specify where not to run the staging jobs (hard requirement).
staging.schedulingTag.soft	"~<IM_tag>"	IM tag to specify where not to run the staging jobs (soft requirement).

See Using staging tags for guidance.

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	Map and unmap routes and jobs.
permit	create	Add routes.
permit	read	Read (use) routes.
permit	update	Update routes.
permit	delete	Delete routes.
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.

Secrets permissions

Policy permissions on resources in the secrets::/ realm and descendant realms control which users can create, read, and delete secrets.

The following consequents are applicable to the secrets::/ realm and all descendant realms.

Claim Type	Claim Value	Description
permit	create	Permit the import of a certificate or private key.
permit	read	Permit the use, list or show secrets.
permit	delete	Permit the deletion of secrets in the designated namespace.
domain.allow	User defined	List of one or more domains

See Secret Policy Examples for guidance.

Semantic pipeline rule 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.

Initial parameter claim for services

Use policy to automate the enforcement of encryption for APCFS and SMB services. Any job bound to an encrypted APCFS or SMB service has its data encrypted.

You apply policy on resources in the service::/ realm.

Claim Type	Claim Value	Description
initial.params	encrypt	Enforce the encryption of local (ephemeral) application data.

See Encryption at Rest Policy Examples for guidance.

Note that application data encryption can only be enforced using policy at service creation time, not on service update.

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.

Subnetpool permissions

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

Claim Type	Claim Value	Description
permit	create	Create a new subnet pool for use with virtual networks.
permit	read	Read the configuration of a subnet pool.
permit	delete	Delete a subnet pool.

See Subnetpool policy examples for guidance.