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:
-
Log in to the web console.
-
Select the Policy icon.
-
Select the policy document you want to edit.
-
Click
Edit Policy
to open the policy in the policy editor. -
Edit the policy.
-
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.
-
If necessary, click cancel to cancel policy edits.
-
Click
Back
to return to the policy home page.
Creating policy documents
Policy document creation requires permissions on the root policydoc::/
realm.
-
From the policy home page, click
Create
. -
Create the policy, or use the comments tag (
#
) to create a blank document with comments. -
Click
Apply
. The policy editor validates the syntax for you. -
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:
-
At the policy home page, click the
Upload
button. -
Browse to and select the policy documents you want to upload.
-
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:
- Create a text file with a
.pol
extension. - Author policy rules that conform to the policy syntax.
- 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