Working with Policies

Apcera provides you with tools for working with policies, including the web-based policy editor, and the APC client. The system also includes various default policies to bootstrap the system. The documentation provides several policy examples to help you write policy.

This section describes how to use the policy editor and APC to work with policy.

Policy permissions required

Like all other resources in the system, to use policy you must have sufficient policy permissions.

To view or update policy, you need permissions on the policy::/ realm and on each resource declared in that policy. For example, you may be able to edit policy on one realm, such as jobs::/, but not another, such as policy::/.

Policy creation and editing permissions are assigned to admin users on cluster creation. After that it is up to an administrator to create the necessary permissions for other users to edit policies and create policy documents. See the Policy on Policy Examples for details.

Using the policy editor

The web console has a built-in policy editor that you can use to read and edit policies (assuming appropriate permissions). On save the policy editor parses the policy document and checks the syntax for your policy rules.

To use the web console for policy authoring:

1. Log in to the web console.

2. Select the Policy​ icon.

3. Select the policy document you want to edit.

4. Click Edit Policy to open the policy in the policy editor.

5. Edit the policy.

6. Click Apply Changes.

   The policy editor validates the syntax for the policy document and, if valid, saves the policy changes. If the policy is malformed, the system reports an error message indicating what is wrong with the syntax.

   In addition, if applicable the policy editor will report what jobs will be out of compliance when the policy is applied. On job restart, jobs that are not in compliance will be impacted by the policy changes.

7. If necessary, click cancel to cancel policy edits.

8. Click Back to return to the policy home page.

Creating policy documents

Policy document creation requires permissions on the root policydoc::/ realm.

1. From the policy home page, click Create.

2. Create the policy, or use the comments tag (#) to create a blank document with comments.

3. Click Apply. The policy editor validates the syntax for you.

4. Return to the policy home page.

   You should see the newly created policy document.

You can also drag and drop a .pol file onto the policy editor's sidebar to upload it to the system (assuming permissions on the policydoc::/ realm).

Adding policy description

You can add a description to a policy document that will appear in the Policy List screen of the web console. Adding a brief policy description helps policy authors and admins scan the list of policy documents and quickly locate the policy they are looking for without having to open each policy document.

To declare a policy description use the <continuum-policy description="DESC"> tag. For example:

<continuum-policy description="My quota policy">

quota::/sandbox/admin {
    { max.instances 5 }
}

Uploading policy documents

To upload a policy document:

1. At the policy home page, click the Upload button.

2. Browse to and select the policy documents you want to upload.

3. Confirm the upload.

   At the policy home page you should see that the policy document(s) is uploaded.

Using APC for policy administration

Assuming permissions, you can use APC to list, show, import, and export policy documents. You can also show policy rules by realm. For example, apc policy on job shows all policy on all jobs in the cluster.

The policy command lets you interact with your the policies in your cluster.

apc policy <subcommand> [optional args]

The following subcommands are supported:

Command	Description
delete	Delete policy document(s) from the cluster (apc policy delete myDoc)
export	Export policy document(s) from the cluster (apc policy export).
import	Import policy documents (apc policy import).
list	List all policy documents in the cluster (apc policy list).
on	Show policy rules by realms (apc policy on job).
show	Shows the source of a policy document (apc policy show authSettings).

apc policy delete

You use this command to delete policy document(s) from the cluster.

apc policy delete <doc> [<doc>...]

For example, to delete a single policy document:

apc policy delete myDoc

Or, to delete multiple policy documents:

apc policy delete myDoc anotherDoc

apc policy export

You use this command to export policy documents from your cluster. You can edit exported policy documents locally and import them back into your cluster using apc policy import.

apc policy export [<document-name>] [options]

NOTE: If no document name is provided all policy documents are exported.

The following command options are supported:

Command	Description
-d, --dir [DIR]	Put exported documents in a given directory. Default is a current workin directory.
-f, --force	Overwrite existing files without asking.

For example, to export all policy documents to the current directory:

apc policy export

Or, to export a specific policy document to a specific directory:

apc policy export authSettings --dir /path/to/dir

apc policy import

You use this command to import policy documents to your cluster.

apc policy import <filename.pol> [<filename.pol>...]

For example, to import a policy document:

1. Create a text file with a .pol extension.
2. Author policy rules that conform to the policy syntax.
3. Import the policy file to your cluster:

apc policy import /path/to/policydoc.pol

Policy import supports wildcards:

apc policy import *.pol

apc policy on

Displays all policy that applies to the given FQN. For example: apc policy on job::/prod/a displays policy on the FQN job::/prod/a, the namespace job::/prod, and the resource root job::/.

apc policy on [<filter>] [-a]

Command	Description
-a, --all	Display all policy for that FQN.

For example:

• To display all policy: apc policy on /

• To display policy on jobs only: apc policy on job

• To display policy on packages in the /dev namespace: apc policy on package::/dev

• To display policy on anything in the /prod namespace: apc policy on /prod

• To display all policy that applies to the FQN job::/dev::myjob: apc policy on job::/dev::myjob -a

• To display all policies on the job::/ realm: apc policy on job

• To display all policies on the namespace realm: apc policy on job::/sandbox/james