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.