--- /dev/null
+.. This work is licensed under a Creative Commons Attribution 4.0 International License.\r
+.. http://creativecommons.org/licenses/by/4.0\r
+\r
+.. _walkthrough:\r
+\r
+Walk-through\r
+============\r
+\r
+The goal of this quickstart is to provide an overview of the\r
+functionalities of the ``dcae-cli`` and walk you through the\r
+capabilities:\r
+\r
+- `Adding data formats <#adding-data-formats>`__\r
+- `Adding component <#adding-component>`__\r
+- `Setting profile <#setting-profile>`__\r
+- `Development and testing <#development-and-testing>`__\r
+- `Publishing component <#publishing-component>`__\r
+- `Shared catalog <#shared-catalog>`__\r
+\r
+.. This walk-through uses example projects: COMMENTED OUT FOR NOW TBD\r
+.. \r
+.. - `laika <ONAP%20URL%20TBD>`__\r
+.. - `CDAP examples <ONAP%20URL%20TBD>`__\r
+\r
+.. _adding-data-formats:\r
+\r
+Adding data formats\r
+-------------------\r
+\r
+``data_format`` is the sub-command that is used to execute operations\r
+that manage `data formats <../data-formats.md>`__.\r
+\r
+::\r
+\r
+ $ dcae_cli data_format --help\r
+ Usage: dcae_cli data_format [OPTIONS] COMMAND [ARGS]...\r
+\r
+ Options:\r
+ --help Show this message and exit.\r
+\r
+ Commands:\r
+ add Tracks a data format file SPECIFICATION...\r
+ generate Generates a data format file from JSON input examples\r
+ list Lists all your data formats\r
+ publish Publishes data format to make publicly...\r
+ show Provides more information about FORMAT\r
+\r
+Your data format must be in the catalog in order to use in the component\r
+specification. Check the catalog using the ``data_format list``\r
+sub-command:\r
+\r
+::\r
+\r
+ $ dcae_cli data_format list\r
+\r
+ Data formats for mh677g\r
+ +------+---------+-------------+--------+----------+\r
+ | Name | Version | Description | Status | Modified |\r
+ +------+---------+-------------+--------+----------+\r
+ | | | | | |\r
+ +------+---------+-------------+--------+----------+\r
+\r
+The fields ``name``, ``version``, ``description`` are referenced from\r
+the data format JSON from the ``self`` JSON.\r
+\r
+There are no data formats so you must add the data formats that your\r
+component specification references. Use the ``data_format add``\r
+sub-command:\r
+\r
+Here’s an example command:\r
+\r
+::\r
+\r
+ dcae_cli data_format add health.json\r
+\r
+Verify that it was added:\r
+\r
+::\r
+\r
+ $ dcae_cli data_format list\r
+\r
+ Data formats for mh677g\r
+ +-------------------------------+---------+-------------------------------------------+--------+----------------------------+\r
+ | Name | Version | Description | Status | Modified |\r
+ +-------------------------------+---------+-------------------------------------------+--------+----------------------------+\r
+ | sandbox.platform.laika.health | 0.1.0 | Data format used for the /health endpoint | staged | 2017-05-23 04:02:38.952799 |\r
+ +-------------------------------+---------+-------------------------------------------+--------+----------------------------+\r
+\r
+Go ahead and add other referenced data formats.\r
+\r
+If you have JSON input you can generate a data format like this:\r
+\r
+::\r
+\r
+ $ dcae_cli data_format --keywords generate myname:1.0.0 myjsoninputfile\r
+\r
+where ``myname`` is the name of your data format, ``1.0.0`` is an\r
+example version, and ``myjsoninputfile`` is an example JSON input file\r
+(a directory of input JSON files can also be provided). The\r
+``--keywords`` option adds additional data attributes that can be\r
+completed to provide a more detailed data characterization. In any event\r
+the output should be reviewed for accuracy. The data format is written\r
+to stdout.\r
+\r
+.. _adding-component:\r
+\r
+Adding component\r
+----------------\r
+\r
+``component`` is the sub-command that is used to work with operations\r
+for components:\r
+\r
+::\r
+\r
+ $ dcae_cli component --help\r
+ Usage: dcae_cli component [OPTIONS] COMMAND [ARGS]...\r
+\r
+ Options:\r
+ --help Show this message and exit.\r
+\r
+ Commands:\r
+ add\r
+ dev Set up component in development for...\r
+ list Lists components in the public catalog.\r
+ publish Pushes COMPONENT to the public catalog\r
+ run Runs the latest version of COMPONENT.\r
+ show Provides more information about COMPONENT\r
+ undeploy Undeploys the latest version of COMPONENT.\r
+\r
+Your component must be accessible from the catalog in order for it to be\r
+used. Check the catalog using the ``component list`` sub-command:\r
+\r
+::\r
+\r
+ $ dcae_cli component list\r
+ Active profile: solutioning\r
+\r
+ +------+---------+------+-------------+--------+----------+-----------+\r
+ | Name | Version | Type | Description | Status | Modified | #Deployed |\r
+ +------+---------+------+-------------+--------+----------+-----------+\r
+ | | | | | | | |\r
+ +------+---------+------+-------------+--------+----------+-----------+\r
+\r
+ Use the "--deployed" option to see more details on deployments\r
+\r
+The fields ``name``, ``version``, ``type``, ``description`` are\r
+referenced from the component specification’s ``self`` JSON.\r
+\r
+There are no components so you must add your component. Use the\r
+``component add`` sub-command. The command is the same for docker and\r
+cdap components:\r
+\r
+::\r
+\r
+ $ dcae_cli component add --help\r
+ Usage: dcae_cli component add [OPTIONS] SPECIFICATION\r
+\r
+ Options:\r
+ --update Updates a locally added component if it has not been already\r
+ pushed\r
+ --help Show this message and exit.\r
+\r
+*Note* use the ``--update`` flag to replace existing staged instances.\r
+\r
+The ``component dev`` sub-command can be useful in validating and\r
+experimenting when crafting your component specification. See details\r
+about ``dev`` under `Development and\r
+testing <#development-and-testing>`__.\r
+\r
+Once we add the components laika and helloworld, let’s verify that they\r
+got added ok:\r
+\r
+::\r
+\r
+ $ dcae_cli component list\r
+ Active profile: solutioning\r
+\r
+ +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
+ | Name | Version | Type | Description | Status | Modified | #Deployed |\r
+ +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
+ | cdap.helloworld.endnode | 0.8.0 | cdap | cdap test component | staged | 2017-05-23 04:14:35.588075 | 0 |\r
+ | sandbox.platform.laika | 0.5.0 | docker | Web service used as a stand-alone test DCAE service compone.. | staged | 2017-05-23 04:07:44.065610 | 0 |\r
+ +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
+\r
+ Use the "--deployed" option to see more details on deployments\r
+\r
+.. _setting-profile:\r
+\r
+Setting profile\r
+---------------\r
+\r
+``profile`` is the sub-command that is used to manage profiles. These\r
+profiles contain environment variables used to connect to different\r
+environments. This is used in the running and deployment of your\r
+component using the ``dcae_cli component run`` command. The ``dcae-cli``\r
+ships with profiles for ``solutioning`` and ``rework``.\r
+\r
+::\r
+\r
+ $ dcae_cli profiles --help\r
+ Usage: dcae_cli profiles [OPTIONS] COMMAND [ARGS]...\r
+\r
+ Options:\r
+ --help Show this message and exit.\r
+\r
+ Commands:\r
+ activate Sets profile NAME as the active profile\r
+ create Creates a new profile NAME initialized with...\r
+ delete Deletes profile NAME\r
+ list Lists available profiles\r
+ set Updates profile NAME such that KEY=VALUE\r
+ show Prints the profile dictionary\r
+\r
+To see what variables a profile contains, you can use the ``show``\r
+command, as in ``dcae_cli profiles show PROFILE_NAME``\r
+\r
+Use the ``create`` sub-command to create your own profile and assign new\r
+values using the ``set`` command. Afterwards you will need to\r
+``activate`` the profile you wish to use. First take a look at which\r
+profile is active:\r
+\r
+::\r
+\r
+ $ dcae_cli profiles list\r
+ rework\r
+ * solutioning\r
+\r
+The active profile is ``solutioning`` so to activate *rework* to use\r
+``rework``:\r
+\r
+::\r
+\r
+ $ dcae_cli profiles activate rework\r
+\r
+Check\r
+\r
+::\r
+\r
+ $ dcae_cli profiles list\r
+ * rework\r
+ solutioning\r
+\r
+.. _development-and-testing:\r
+\r
+Development and testing\r
+-----------------------\r
+\r
+The following operations under the sub-command ``component`` are aimed\r
+to help developers with testing:\r
+\r
+- ``run``\r
+- ``undeploy``\r
+- ``dev``\r
+\r
+``run``\r
+~~~~~~~\r
+\r
+The ``run`` operation is to be used for running your application in its\r
+container remotely on the activated environment. Docker containers have\r
+the additional option to run locally on your development machine.\r
+\r
+In order to run your application, you must have added your data formats\r
+and your component to your catalog.\r
+\r
+Let’s verify that your component is in the catalog:\r
+\r
+::\r
+\r
+ $ dcae_cli component list \r
+ Active profile: solutioning\r
+\r
+ +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
+ | Name | Version | Type | Description | Status | Modified | #Deployed |\r
+ +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
+ | cdap.helloworld.endnode | 0.8.0 | cdap | cdap test component | staged | 2017-05-23 04:14:35.588075 | 0 |\r
+ | sandbox.platform.laika | 0.5.0 | docker | Web service used as a stand-alone test DCAE service compone.. | staged | 2017-05-23 04:07:44.065610 | 0 |\r
+ +-------------------------+---------+--------+---------------------------------------------------------------+--------+----------------------------+-----------+\r
+\r
+ Use the "--deployed" option to see more details on deployments\r
+\r
+Docker\r
+^^^^^^\r
+\r
+**NOTE** Make sure your Docker image has been uploaded to the shared\r
+registry.\r
+\r
+For Docker containers, you can run either attached or unattached.\r
+Attached means that the dcae-cli tool will launch the container and not\r
+terminate. The dcae-cli while attached will stream in the logs of the\r
+Docker container. Doing a Ctrl-C will terminate the run session which\r
+means undeploy your container and force a clean up automatically.\r
+\r
+Running unattached means simply deploy your container. You will need to\r
+execute ``undeploy`` when you are done testing. #### CDAP\r
+\r
+**NOTE** Make sure your CDAP jar has been uploaded to Nexus.\r
+\r
+TODO\r
+\r
+``undeploy``\r
+~~~~~~~~~~~~\r
+\r
+The ``undeploy`` operation is to be used to undeploy any instances of a\r
+specified component, version that you have deployed. This includes\r
+cleaning up of configuration.\r
+\r
+Let’s undeploy ``sandbox.platform.laika`` that was deployed from the\r
+previous section:\r
+\r
+::\r
+\r
+ $ dcae_cli component undeploy sandbox.platform.laika:0.5.0\r
+ DCAE.Undeploy | WARNING | Undeploying components: 1\r
+ DCAE.Undeploy | WARNING | Undeployed components: 1\r
+\r
+.. _walkthrough-dev:\r
+\r
+``dev``\r
+~~~~~~~\r
+\r
+The ``dev`` operation is a convenient operation that can be useful for\r
+the development and testing of your component. It can be used to:\r
+\r
+- Help validate your experimental component specification before\r
+ uploading to the catalog\r
+- Generate the application configuration from the component\r
+ specification and make it available in a test environment. This\r
+ allows you to view your resulting configuration for local development\r
+ and to help debug potential related issues.\r
+\r
+Let’s say you have a component specification called\r
+``component-spec.json``:\r
+\r
+::\r
+\r
+ $ dcae_cli component dev component-spec.json \r
+ Ready for component development\r
+\r
+ Setup these environment varibles. Run "source env_solutioning":\r
+\r
+ export DOCKER_HOST=SOME_DOCKER_HOST:2376\r
+ export SERVICE_CHECK_INTERVAL=15s\r
+ export CONFIG_BINDING_SERVICE=config_binding_service\r
+ export HOSTNAME=mh677g.95740959-63d2-492a-b964-62a6dce2591d.0-6-0.sandbox-platform-laika\r
+ export CONSUL_HOST=SOME_CONSUL_HOST\r
+ export CDAP_BROKER=cdap_broker\r
+ export SERVICE_NAME=mh677g.95740959-63d2-492a-b964-62a6dce2591d.0-6-0.sandbox-platform-laika\r
+ export SERVICE_CHECK_TIMEOUT=1s\r
+ export SERVICE_CHECK_HTTP=/health\r
+\r
+ Press any key to stop and to clean up\r
+\r
+Your application configuration is now available under the name\r
+``mh677g.95740959-63d2-492a-b964-62a6dce2591d.0-6-0.sandbox-platform-laika``.\r
+\r
+To view the resulting configuration, you can ``curl`` a request to the\r
+config binding service or programmatically fetch your configuration\r
+within your application.\r
+\r
+You need to first query Consul to get the ip and port of config binding\r
+service:\r
+\r
+::\r
+\r
+ curl http://$CONSUL_HOST:8500/v1/catalog/service/$CONFIG_BINDING_SERVICE\r
+ [\r
+ {\r
+ "ID": "983d5c94-c508-4a8a-9be3-5912bd09786b",\r
+ "Node": "realsolcnsl00",\r
+ "Address": "10.226.1.22",\r
+ "TaggedAddresses": {\r
+ "lan": "10.226.1.22",\r
+ "wan": "10.226.1.22"\r
+ },\r
+ "NodeMeta": {},\r
+ "ServiceID": "5f371f295c90:config_binding_service:10000",\r
+ "ServiceName": "config_binding_service",\r
+ "ServiceTags": [],\r
+ "ServiceAddress": "XXXX",\r
+ "ServicePort": 32770,\r
+ "ServiceEnableTagOverride": false,\r
+ "CreateIndex": 487,\r
+ "ModifyIndex": 487\r
+ }\r
+ ]\r
+\r
+.. _dmaap-testing:\r
+\r
+DMaaP testing\r
+~~~~~~~~~~~~~\r
+\r
+Currently, the dcae-cli does not have the capability of provisioning\r
+topics. In order to do testing with message router topics or with data\r
+router feeds, the developer must provision the topic or the feed\r
+manually and provide the connection details in the form of a JSON in a\r
+file to the dcae-cli. This file is to be passed in when using the\r
+``run`` and ``dev`` commands with the option ``--dmaap-file``.\r
+\r
+The structure of the DMaaP JSON is an object of config keys to matching\r
+topic or feed connection details. Config keys are the ``config_key``\r
+values specified in your component specification streams section where\r
+the streams must be type message router or data router. Information\r
+about the associated connection details can be found on `this\r
+page <dmaap-connection-objects.md>`__. Please check it out.\r
+\r
+For example, if you have a component specification that has the\r
+following streams entry:\r
+\r
+.. code:: json\r
+\r
+ "streams": {\r
+ "publishes": [{\r
+ "format": "ves",\r
+ "version": "1.0.0",\r
+ "type": "message router",\r
+ "config_key": "ves_connection"\r
+ }]\r
+ }\r
+\r
+Then to deploy and to run your component, you must use the\r
+``--dmaap-file`` command and pass in a JSON that looks like:\r
+\r
+.. code:: json\r
+\r
+ {\r
+ "ves_connection": {\r
+ "type": "message_router",\r
+ "dmaap_info": {\r
+ "topic_url": "https://we-are-message-router.us:3905/events/some-topic"\r
+ }\r
+ }\r
+ }\r
+\r
+The provided DMaaP JSON is used to simulate the output of provisioning\r
+and will be used to merge with the generated application configuration\r
+at runtime.\r
+\r
+Your final application config will look like:\r
+\r
+.. code:: json\r
+\r
+ {\r
+ "streams_publishes": {\r
+ "ves_connection": {\r
+ "type": "message_router",\r
+ "dmaap_info": {\r
+ "topic_url": "https://we-are-message-router.us:3905/events/some-topic"\r
+ }\r
+ }\r
+ }\r
+ }\r
+\r
+Data router subscribers\r
+^^^^^^^^^^^^^^^^^^^^^^^\r
+\r
+Note for data router subscriber testing, you will need the delivery url\r
+in order to provision the subscriber to the feed. This is constructed at\r
+deployment time and will be provided by the dcae-cli after you deploy\r
+your component. The delivery urls will be displayed to the screen:\r
+\r
+::\r
+\r
+ DCAE.Run | WARNING | Your component is a data router subscriber. Here are the delivery urls: \r
+\r
+ some-sub-dr: http://SOME_IP:32838/identity\r
+\r
+*Sourced at deployment* testing\r
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~\r
+\r
+Components may have configuration parameters whose values are to be\r
+sourced at deployment time. For example, there are components whose\r
+configuration parameters are to come from DTI events which are only\r
+available when the component is getting deployed. These configuration\r
+parameters must be setup correctly in the `component\r
+specification <http://localhost:8000/components/component-specification/docker-specification/#configuration-parameters>`__\r
+by setting the property ``sourced_at_deployment`` to ``true`` for each\r
+and every parameter that is expected to come in at deployment time.\r
+\r
+Once your component specification has been updated correctly, you must\r
+use the ``--inputs-file`` command-line argument when running the\r
+commands ``dev`` or ``run`` with your component. This is to simulate\r
+providing the dynamic, deployment time values for those parameters\r
+marked as ``sourced_at_deployment``.\r
+\r
+For example, if your component specification has the following\r
+configuration parameters:\r
+\r
+::\r
+\r
+ "parameters": [{\r
+ "name": "vnf-ip",\r
+ "value": "",\r
+ "sourced_at_deployment": true\r
+ },\r
+ {\r
+ "name": "static-param",\r
+ "value": 5\r
+ }]\r
+\r
+You would have to pass in an inputs file that looks like:\r
+\r
+::\r
+\r
+ {\r
+ "vnf-ip": "10.100.1.100"\r
+ }\r
+\r
+Your application configuration would look like:\r
+\r
+::\r
+\r
+ {\r
+ "vnf-ip": "10.100.1.100",\r
+ "static-param": 5\r
+ }\r
+\r
+Publishing component\r
+--------------------\r
+\r
+Once components have their component specifications crafted and\r
+validated and have been tested, components should be published in the\r
+shared onboarding catalog using the ``publish`` sub-command for both\r
+data formats and components. You must publish all data formats of a\r
+component before publishing a component.\r
+\r
+Publishing will change the status of a component, be made accessible for\r
+other developers to use, and will generate the associated TOSCA models\r
+for use in designing of compositions.\r
+\r
+::\r
+\r
+ dcae_cli component publish sandbox.platform.laika:0.5.0\r
+\r
+Shared catalog\r
+--------------\r
+\r
+``catalog`` is the sub-command used to access and to browse the shared\r
+onboarding catalog to view components and data formats that have been\r
+published and that are being worked on. Components and data formats have\r
+two statuses ``staged`` and ``published``.\r
+\r
+Staged means that the resource has been simply added and is under\r
+development. It is to be used only by the owner. Published means that\r
+the resource has been fully developed and tested and is ready to be\r
+shared.\r
+\r
+Published components can be deployed by non-owners and published data\r
+formats can be used in component specifications of non-owners.\r
+\r
+There are two available operations:\r
+\r
+::\r
+\r
+ $ dcae_cli catalog --help\r
+ Usage: dcae_cli catalog [OPTIONS] COMMAND [ARGS]...\r
+\r
+ Options:\r
+ --help Show this message and exit.\r
+\r
+ Commands:\r
+ list\r
+ show\r
+\r
+Staged components can be viewed under the ``list`` operation using the\r
+``--expanded`` flag.\r
Code Review / dcaegen2.git / blobdiff