dcae-services-policy-sync/README.md

   1 # Policy Sync\r
   2 This page serves as an implementation for the Policy sync container described in the [wiki](https://wiki.onap.org/display/DW/Policy+function+as+Sidecar)\r
   3 \r
   4 Policy Sync utility is a python based utility that interfaces with the ONAP/ECOMP policy websocket and REST APIs. It is designed to keep a local listing of policies in sync with an environment's policy distribution point (PDP). It functions well as a Kubernetes sidecar container which can pull down the latest policies for consumption by an application container. \r
   5 \r
   6 The sync utility primarily utilizes the PDP's websocket notification API to receive policy update notifications. It also includes a periodic check of the  PDP for resilliency purposes in the event of websocket API issues. \r
   7 \r
   8 Policy Sync provides a way to realize runtime configuration for DCAE microservices through Policy Module. \r
   9 \r
  10 Currently, SON-Handler and SliceMS is utilizing policy sync.\r
  11 \r
  12 ## Build and Run\r
  13 Easiest way to use is via docker by building the provided docker file\r
  14 \r
  15 ```bash\r
  16 docker build . -t policy-puller\r
  17 ```\r
  18 \r
  19 If you want to run it in a non containerized environment, an easy way is to use python virtual environments.\r
  20 ```bash\r
  21 # Create a virtual environment in venv folder and activate it\r
  22 python3 -m venv venv\r
  23 source venv/bin/activate\r
  24 \r
  25 # install the utility\r
  26 pip install .\r
  27 \r
  28 # Utility is now installed and usable in your virtual environment. Test it with:\r
  29 policysync -h \r
  30 ```\r
  31 \r
  32 ## Configuration\r
  33 \r
  34 Configuration is currently done via either env variables or by flag. Flags take precedence env variables, env variables take precedence over default\r
  35 \r
  36 ### General configuration\r
  37 General configuration that is used regardless of which PDP API you are using. \r
  38 \r
  39 | ENV Variable              | Flag               | Description                                  | Default                           |\r
  40 | --------------------------| -------------------|----------------------------------------------|-----------------------------------|\r
  41 | POLICY_SYNC_PDP_URL       | --pdp-url          | PDP URL to query                             | None (must be set in env or flag) |\r
  42 | POLICY_SYNC_FILTER        | --filters          | yaml list of regex of policies to match      | []                                |\r
  43 | POLICY_SYNC_ID            | --ids              | yaml list of ids of policies to match        | []                                |\r
  44 | POLICY_SYNC_DURATION      | --duration         | duration in seconds for periodic checks      | 1200                              |\r
  45 | POLICY_SYNC_OUTFILE       | --outfile          | File to output policies to                   | ./policies.json                   |\r
  46 | POLICY_SYNC_PDP_USER      | --pdp-user         | Set user if you need basic auth for PDP      | None                              |\r
  47 | POLICY_SYNC_PDP_PASS      | --pdp-password     | Set pass if you need basic auth for PDP      | None                              |\r
  48 | POLICY_SYNC_HTTP_METRICS  | --http-metrics     | Whether to expose prometheus metrics         | True                              |  \r
  49 | POLICY_SYNC_HTTP_BIND     | --http-bind        | host:port for exporting prometheus metrics   | localhost:8000                    |\r
  50 | POLICY_SYNC_LOGGING_CONFIG| --logging-config   | Path to a python formatted logging file      | None (logs will write to stderr)  |\r
  51 | POLICY_SYNC_V0_ENABLE     | --use-v0         | Set to true to enable usage of legacy v0 API   | False                             |\r
  52 \r
  53 ### V1 Specific Configuration (Used as of the Dublin release)\r
  54 Configurable variables used for the V1 API used in the ONAP Dublin Release.\r
  55 \r
  56 Note: Policy filters are not currently supported in the current policy release but will be eventually. \r
  57 \r
  58 | ENV Variable                     | Flag                   | Description                            | Default                      |\r
  59 | ---------------------------------|------------------------|----------------------------------------|------------------------------|\r
  60 | POLICY_SYNC_V1_DECISION_ENDPOINT | --v1-decision-endpoint | Endpoint to query for PDP decisions    | policy/pdpx/v1/decision      |\r
  61 | POLICY_SYNC_V1_DMAAP_URL         | --v1-dmaap-topic       | Dmaap url with topic for notifications | None                         |\r
  62 | POLICY_SYNC_V1_DMAAP_USER        | --v1-dmaap-user        | User to use for DMaaP notifications    | None                         |\r
  63 | POLICY_SYNC_V1_DMAAP_PASS        | --v1-dmaap-pass        | Password to use for DMaaP notifications| None                         |\r
  64 \r
  65 \r
  66 \r
  67 ### V0 Specific Configuration (Legacy Policy API)\r
  68 Configurable variables used for the legacy V0 API Prior to the ONAP release. Only valid when --use-v0 is set to True\r
  69 \r
  70 \r
  71 | ENV Variable                     | Flag                   | Description                            | Default                      |\r
  72 | ---------------------------------|------------------------|----------------------------------------|------------------------------|\r
  73 | POLICY_SYNC_V0_NOTIFIY_ENDPOINT  | --v0-notifiy-endpoint  | websock endpoint for pdp notifications |  pdp/notifications           |\r
  74 | POLICY_SYNC_V0_DECISION_ENDPOINT | --v0-decision-endpoint | rest endpoint for pdp decisions        |  pdp/api                     |\r
  75 \r
  76 ## Usage\r
  77 \r
  78 You can run in a pure docker setup:\r
  79 ```bash\r
  80 # Run the container\r
  81 docker run \r
  82     --env POLICY_SYNC_PDP_USER=<username> \\r
  83     --env POLICY_SYNC_PDP_PASS=<password> \\r
  84     --env POLICY_SYNC_PDP_URL=<path_to_pdp> \\r
  85     --env POLICY_SYNC_V1_DMAAP_URL='https://<dmaap_host>:3905/events/<dmaap_topic>' \\r
  86     --env POLICY_SYNC_V1_DMAAP_PASS='<user>' \\r
  87     --env POLICY_SYNC_V1_DMAAP_USER='<pass>' \\r
  88     --env POLICY_SYNC_ID=['DCAE.Config_MS_AGING_UVERSE_PROD'] \\r
  89     -v $(pwd)/policy-volume:/etc/policy \\r
  90     nexus3.onap.org:10001/onap/org.onap.dcaegen2.deployments.policy-sync:1.0.1\r
  91 ```\r
  92 \r
  93 Or on Kubernetes: \r
  94 ```yaml\r
  95 # policy-config-map\r
  96 apiVersion: v1\r
  97 kind: policy-config-map\r
  98 metadata:\r
  99   name: special-config\r
 100   namespace: default\r
 101 data:\r
 102   POLICY_SYNC_PDP_USER: myusername\r
 103   POLICY_SYNC_PDP_PASS: mypassword\r
 104   POLICY_SYNC_PDP_URL: <path_to_pdp>\r
 105   POLICY_SYNC_V1_DMAAP_URL: 'https://<dmaap_host>:3905/events/<dmaap_topic>' \\r
 106   POLICY_SYNC_V1_DMAAP_PASS: '<user>' \\r
 107   POLICY_SYNC_V1_DMAAP_USER: '<pass>' \\r
 108   POLICY_SYNC_FILTER: '["DCAE.Config_MS_AGING_UVERSE_PROD"]'\r
 109   \r
 110   \r
 111 ---\r
 112 \r
 113 apiVersion: v1\r
 114 kind: Pod\r
 115 metadata:\r
 116   name: Sidecar sample app\r
 117 spec:\r
 118   restartPolicy: Never\r
 119  \r
 120  \r
 121   # The shared volume that the two containers use to communicate...empty dir for simplicity\r
 122   volumes:\r
 123   - name: policy-shared\r
 124     emptyDir: {}\r
 125  \r
 126   containers:\r
 127  \r
 128   # Sample app that uses inotifyd (part of busybox/alpine). For demonstration purposes only...\r
 129   - name: main\r
 130     image: nexus3.onap.org:10001/onap/org.onap.dcaegen2.deployments.policy-sync:1.0.1\r
 131     volumeMounts:\r
 132     - name: policy-shared\r
 133       mountPath: /etc/policies.json\r
 134       subPath: policies.json\r
 135     # For details on what this does see: https://wiki.alpinelinux.org/wiki/Inotifyd\r
 136     # you can replace '-' arg below with a shell script to do more interesting\r
 137     cmd: [ "inotifyd", "-", "/etc/policies.json:c" ]\r
 138  \r
 139  \r
 140     # The sidecar app which keeps the policies in sync\r
 141   - name: policy-sync\r
 142     image: nexus3.onap.org:10001/onap/org.onap.dcaegen2.deployments.policy-sync:1.0.1\r
 143     envFrom:\r
 144       - configMapRef:\r
 145           name: special-config\r
 146     \r
 147     volumeMounts:\r
 148     - name: policy-shared\r
 149       mountPath: /etc/policies\r
 150 ```\r
 151 \r
 152 ## How to apply\r
 153 Steps to utilize policy sync as a way to do runtime configuration:\r
 154 1. Create policy Type: curl -k -v --user '<policyApiUserName>:<policyApiPassword>' -X POST "https://{{Policy-API-IP}}:6969/policy/api/v1/policytypes" -H "Content-Type:application/json" -H "Accept: application/json" -d @policy_type.json \r
 155 2. Create xcaml policy: curl -v -k --silent --user '<policyApiUserName>:<policyApiPassword>' -X POST "https://{{Policy-API-IP}}:6969/policy/api/v1/policytypes/{{PolicyType}}}/versions/{PolicyVersion}/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @policy.json\r
 156    * URL param "PolicyType" value is used to tell policy api which policy type should the current policy belongs to\r
 157    * URL param "PolicyType" value should refer to Policy Type Name you define in policy_type.json\r
 158    * URL param "PolicyVersion" value should refer to Version you define in policy.json\r
 159    * "Policy Id" defines in policy.json should be consistent with the "policyID" in /oom/kubernetes/dcaegen2-services/components/dcae-slice-analysis-ms/values.yaml\r
 160 3. Deploy policy to xacml pdp engine: curl --silent -k --user '<policyApiUserName>:<policyApiPassword>' -X POST "https://{{Policy-PAP-IP}}:6969/policy/pap/v1/pdps/policies" -H "Accept: application/json" -H "Content-Type: application/json" -d @deploy.json\r
 161 4. Example policy_type.json, policy.json, deploy.json can be found in resources \r
 162 Notice: Default '<policyApiUserName>:<policyApiPassword>' & '<policyApiUserName>:<policyApiPassword>' value is 'policyadmin:zb!XztG34'\r