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 \r
   5 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
   6 \r
   7 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
   8 \r
   9 \r
  10 ## Build and Run\r
  11 Easiest way to use is via docker by building the provided docker file\r
  12 \r
  13 ```bash\r
  14 docker build . -t policy-puller\r
  15 ```\r
  16 \r
  17 If you want to run it in a non containerized environment, an easy way is to use python virtual environments.\r
  18 ```bash\r
  19 # Create a virtual environment in venv folder and activate it\r
  20 python3 -m venv venv\r
  21 source venv/bin/activate\r
  22 \r
  23 # install the utility\r
  24 pip install .\r
  25 \r
  26 # Utility is now installed and usable in your virtual environment. Test it with:\r
  27 policysync -h \r
  28 ```\r
  29 \r
  30 ## Configuration\r
  31 \r
  32 Configuration is currently done via either env variables or by flag. Flags take precedence env variables, env variables take precedence over default\r
  33 \r
  34 ### General configuration\r
  35 General configuration that is used regardless of which PDP API you are using. \r
  36 \r
  37 | ENV Variable              | Flag               | Description                                  | Default                           |\r
  38 | --------------------------| -------------------|----------------------------------------------|-----------------------------------|\r
  39 | POLICY_SYNC_PDP_URL       | --pdp-url          | PDP URL to query                             | None (must be set in env or flag) |\r
  40 | POLICY_SYNC_FILTER        | --filters          | yaml list of regex of policies to match      | []                                |\r
  41 | POLICY_SYNC_ID            | --ids              | yaml list of ids of policies to match        | []                                |\r
  42 | POLICY_SYNC_DURATION      | --duration         | duration in seconds for periodic checks      | 2600                              |\r
  43 | POLICY_SYNC_OUTFILE       | --outfile          | File to output policies to                   | ./policies.json                   |\r
  44 | POLICY_SYNC_PDP_USER      | --pdp-user         | Set user if you need basic auth for PDP      | None                              |\r
  45 | POLICY_SYNC_PDP_PASS      | --pdp-password     | Set pass if you need basic auth for PDP      | None                              |\r
  46 | POLICY_SYNC_HTTP_METRICS  | --http-metrics     | Whether to expose prometheus metrics         | True                              |  \r
  47 | POLICY_SYNC_HTTP_BIND     | --http-bind        | host:port for exporting prometheus metrics   | localhost:8000                    |\r
  48 | POLICY_SYNC_LOGGING_CONFIG| --logging-config   | Path to a python formatted logging file      | None (logs will write to stderr)  |\r
  49 | POLICY_SYNC_V0_ENABLE     | --use-v0         | Set to true to enable usage of legacy v0 API   | False                             |\r
  50 \r
  51 ### V1 Specific Configuration (Used as of the Dublin release)\r
  52 Configurable variables used for the V1 API used in the ONAP Dublin Release.\r
  53 \r
  54 Note: Policy filters are not currently supported in the current policy release but will be eventually. \r
  55 \r
  56 | ENV Variable                     | Flag                   | Description                            | Default                      |\r
  57 | ---------------------------------|------------------------|----------------------------------------|------------------------------|\r
  58 | POLICY_SYNC_V1_DECISION_ENDPOINT | --v1-decision-endpoint | Endpoint to query for PDP decisions    | policy/pdpx/v1/decision      |\r
  59 | POLICY_SYNC_V1_DMAAP_URL         | --v1-dmaap-topic       | Dmaap url with topic for notifications | None                         |\r
  60 | POLICY_SYNC_V1_DMAAP_USER        | --v1-dmaap-user        | User to use for DMaaP notifications    | None                         |\r
  61 | POLICY_SYNC_V1_DMAAP_PASS        | --v1-dmaap-pass        | Password to use for DMaaP notifications| None                         |\r
  62 \r
  63 \r
  64 \r
  65 ### V0 Specific Configuration (Legacy Policy API)\r
  66 Configurable variables used for the legacy V0 API Prior to the ONAP release. Only valid when --use-v0 is set to True\r
  67 \r
  68 \r
  69 | ENV Variable                     | Flag                   | Description                            | Default                      |\r
  70 | ---------------------------------|------------------------|----------------------------------------|------------------------------|\r
  71 | POLICY_SYNC_V0_NOTIFIY_ENDPOINT  | --v0-notifiy-endpoint  | websock endpoint for pdp notifications |  pdp/notifications           |\r
  72 | POLICY_SYNC_V0_DECISION_ENDPOINT | --v0-decision-endpoint | rest endpoint for pdp decisions        |  pdp/api                     |\r
  73 \r
  74 ## Usage\r
  75 \r
  76 You can run in a pure docker setup:\r
  77 ```bash\r
  78 # Run the container\r
  79 docker run \r
  80     --env POLICY_SYNC_PDP_USER=<username> \\r
  81     --env POLICY_SYNC_PDP_PASS=<password> \\r
  82     --env POLICY_SYNC_PDP_URL=<path_to_pdp> \\r
  83     --env POLICY_SYNC_V1_DMAAP_URL='https://<dmaap_host>:3905/events/<dmaap_topic>' \\r
  84     --env POLICY_SYNC_V1_DMAAP_PASS='<user>' \\r
  85     --env POLICY_SYNC_V1_DMAAP_USER='<pass>' \\r
  86     --env POLICY_SYNC_ID=['DCAE.Config_MS_AGING_UVERSE_PROD'] \\r
  87     -v $(pwd)/policy-volume:/etc/policy \\r
  88     nexus3.onap.org:10001/onap/org.onap.dcaegen2.deployments.policy-sync:1.0.0\r
  89 ```\r
  90 \r
  91 Or on Kubernetes: \r
  92 ```yaml\r
  93 # policy-config-map\r
  94 apiVersion: v1\r
  95 kind: policy-config-map\r
  96 metadata:\r
  97   name: special-config\r
  98   namespace: default\r
  99 data:\r
 100   POLICY_SYNC_PDP_USER: myusername\r
 101   POLICY_SYNC_PDP_PASS: mypassword\r
 102   POLICY_SYNC_PDP_URL: <path_to_pdp>\r
 103   POLICY_SYNC_V1_DMAAP_URL: 'https://<dmaap_host>:3905/events/<dmaap_topic>' \\r
 104   POLICY_SYNC_V1_DMAAP_PASS: '<user>' \\r
 105   POLICY_SYNC_V1_DMAAP_USER: '<pass>' \\r
 106   POLICY_SYNC_FILTER: '["DCAE.Config_MS_AGING_UVERSE_PROD"]'\r
 107   \r
 108   \r
 109 ---\r
 110 \r
 111 apiVersion: v1\r
 112 kind: Pod\r
 113 metadata:\r
 114   name: Sidecar sample app\r
 115 spec:\r
 116   restartPolicy: Never\r
 117  \r
 118  \r
 119   # The shared volume that the two containers use to communicate...empty dir for simplicity\r
 120   volumes:\r
 121   - name: policy-shared\r
 122     emptyDir: {}\r
 123  \r
 124   containers:\r
 125  \r
 126   # Sample app that uses inotifyd (part of busybox/alpine). For demonstration purposes only...\r
 127   - name: main\r
 128     image: nexus3.onap.org:10001/onap/org.onap.dcaegen2.deployments.policy-sync:1.0.0\r
 129     volumeMounts:\r
 130     - name: policy-shared\r
 131       mountPath: /etc/policies.json\r
 132       subPath: policies.json\r
 133     # For details on what this does see: https://wiki.alpinelinux.org/wiki/Inotifyd\r
 134     # you can replace '-' arg below with a shell script to do more interesting\r
 135     cmd: [ "inotifyd", "-", "/etc/policies.json:c" ]\r
 136  \r
 137  \r
 138     # The sidecar app which keeps the policies in sync\r
 139   - name: policy-sync\r
 140     image: nexus3.onap.org:10001/onap/org.onap.dcaegen2.deployments.policy-sync:1.0.0\r
 141     envFrom:\r
 142       - configMapRef:\r
 143           name: special-config\r
 144     \r
 145     volumeMounts:\r
 146     - name: policy-shared\r
 147       mountPath: /etc/policies\r
 148 ```\r
 149 \r
 150 \r