Anax documentation for deployment policy template syntax

[johnwalicki]

Describe the Documentation bug

This Issue was originally posted to the Docs repo: https://github.com/open-horizon/open-horizon.github.io/issues/90 The suggestion is to move it here.

I want to construct a new deployment policy template file that I can pass to hzn exchange deployment addpolicy -f deployment.policy.json ${HZN_ORG_ID}/policy-${SERVICE_NAME}_${SERVICE_VERSION}

The IEAM / Open Horizon documentation resources do not specify the syntax for the json file.

Specifically, I wanted to add a

  "constraints": [
    "somevalue == true"
  ],

I searched for a very long time and finally found an obscure example that I was able to cobble together.

To Reproduce

Pages that I unsuccessfully looked for answers / solutions:

• https://www.ibm.com/docs/en/edge-computing/4.2?topic=services-developing-edge-service-devices
• https://www.ibm.com/docs/en/edge-computing/4.2?topic=reading-development-details
• https://github.com/open-horizon/anax/blob/master/docs/deployment_string.md
• https://www.ibm.com/docs/en/edge-computing/4.2?topic=services-edge-service-examples

Expected behavior

Search for deployment policy json and a documentation page provides the syntax and example.

Reading resources (optional)

Eventually I found this example https://github.com/open-horizon/examples/blob/master/edge/services/helloworld/CreateService.md which suggests wget https://raw.githubusercontent.com/open-horizon/examples/master/edge/services/helloworld/policy/deployment.policy.json That was a good start. Then I hunted around for the constraints stanza from other examples. When I needed the answer, I never found a documentation page which describes how to do this.

In my attempt to document this issue, I finally searched the documentation for the specific string: hzn exchange deployment addpolicy using this query: https://www.ibm.com/docs/en/search/hzn%20exchange%20deployment%20addpolicy?scope=SSFKVV_4.2

and it led me to the page that I wanted. It was not easy to find... This page needs some more keywords?

https://www.ibm.com/docs/en/edge-computing/4.2?topic=services-deployment-policy-use-cases

Summary

So the answer is "Go here: https://www.ibm.com/docs/en/edge-computing/4.2?topic=services-deployment-policy-use-cases"

This is a REALLY common scenario. A developer creates a Open Horizon service, publishes the service, and wants to deploy a policy for that service. They might put this in a Makefile or some other CI/CD pipeline. The CLI commands need to more discoverable.

[johnwalicki]

@joewxboy writes in https://github.com/open-horizon/open-horizon.github.io/issues/90#issuecomment-923974485

We should fix the documentation that lives in the anax repo to point to the examples. Please close this issue and open it in the anax repo.

[dlarson04]

@johnwalicki Does executing "hzn exchange deployment new" get you the template file you are looking for?

[johnwalicki]

Yes, hzn exchange deployment new emits a well documented template. This is great.

As an edge developer, it would be helpful to have a Edge Developer Getting Started learning path. The https://www.ibm.com/docs/en/eam/4.3?topic=services-deployment-policy-use-cases page contains great details. However, the page is misnamed. "Deployment policy use cases" I would not have thought to start on that page.

I suggest we rename this page. (leaving a placeholder with a redirect?) The menu navigation is wrong too. This page sits in the "Using Edge Services" tree. It really belongs in the "Developing Edge Services" tree.