Skip to content

Latest commit

 

History

History
229 lines (154 loc) · 10.8 KB

usage.md

File metadata and controls

229 lines (154 loc) · 10.8 KB

Usage

This sections describes how to use the CN-WAN Reader, i.e. its flags.

It applies to whatever installation method you chose, but if you are running the program in a docker container, you should also follow Docker Usage after reading this.

You should prefix path/to/cnwan-reader before these commands, or docker run image if you are running the program inside a docker container.

Table of Contents

CN-WAN Adaptor

Adaptors are external handlers that will receive the events sent by the CN-WAN Reader and process them.

By default, CN-WAN Reader sends data to localhost:80/cnwan/events, so it expects adaptors to provide a server listening on localhost:80/cnwan. In case you have a different endpoint or already have a server listening on another host:port or just prefer to use another prefix path - or none at all, you can override this behavior with the -adaptor-api argument:

For example:

--adaptor-api localhost:5588/my/path

Events will be now sent to localhost:5588/my/path/events. As an example of no prefix path, --adaptor-api localhost:8080 will instruct the CN-WAN Reader to send events on localhost:8080/events instead of localhost:8080/cnwan/events. If a port is not provided, 80 will be used as default.

Please follow OpenAPI Specification to learn more about adaptors and Example for a complete usage example that includes a CN-WAN Adaptor endpoint as well.

Metadata Key

The CN-WAN Reader only reads services that have the provided metadata key.

For example, the following flag

--metadata-key cnwan.io/traffic-profile

will make the program only look for services whose metadata contain cnwan.io/traffic-profile and ignore all services that don't have it. Please note that it will only look for the key and will not do any type of filtering on the value, as this job is performed by the CN-WAN Adaptor or whomever is in charge of handling the values.

Service registries

Google Cloud Service Directory

To connect to Google Cloud Service Directory, you can use the servicedirectory command. A region, project and service account path must be provided as flags, like so:

servicedirectory --project my-project --region us-central1 --service-account ...

# With a shorter alias
sd --project my-project --region us-central1 --service-account ...

Providing the service account JSON file is different depending on the way you run the project:

  • if you are running the binary version you can simply read Binary Example for a full example usage.

  • if you are running it as a Docker container, follow Docker Usage, as it needs some additional steps.

Finally, please make sure your service account has at least role roles/servicedirectory.viewer. We suggest you create service account just for the CN-WAN Reader with the aforementioned role.

NOTE: servicedirectory command will be moved to poll command soon, so the full command will be cnwan-reader poll servicedirectory [...].

AWS Cloud Map

To use AWS Cloud Map, you need to run CN-WAN Reader with the poll command like cnwan-reader poll cloudmap [...].

You will need to provide a region to look for with --region and, optionally, a path where your credentials are with --credentials-path. If you have the aws cli installed then you don't need to set this flag, as they should reside in $HOME/.aws/credentials in Unix-based systems or %UserProfile%/.aws/credentials in Windows ones, unless you want to use other credentials.

In order to use CN-WAN Reader with Cloud Map, your IAM identity needs to have at least policy AWSCloudMapReadOnlyAccess or above.

For more information about AWS credentials, you may take a look at aws' documentation about this topic.

etcd

CN-WAN Reader can connect to your etcd nodes and watch the values that have been registered there, i.e. with cnwan-reader watch etcd [FLAGS] .

In order to work, you will need to provide the addresses of your etcd nodes with the --endpoints flag, optional username and password and a prefix in case your service registry on etcd contains one. There is no need to insert all the nodes of your etcd cluster in --endpoints but just make sure you enter a few. As per username and password you can leave them empty if you don't need them to connect to etcd. Finally, prefix defaults to / in case you don't enter another value.

As a final note, make sure your etcd user has a role that enables it to at least read values in the provided prefix.

For more information on flags and examples, please run cnwan-reader watch etcd --help.

Configuration File

Optionally, a configuration file can be used, which can be used by providing its path with --conf. A configuration model is there for you on examples/config.

The fields in the YAML file map to each CLI flag specified in the sections above and therefore you won't need to include them if you want to use the default value, i.e. if pollInterval is not there, then the default value 5 will be used, as specified in --help.

In the provided yaml example, we entered example.com to specify that the adaptor is not running in the same machine as the reader, and that, if not present, the value for host will be localhost and 80 for port. If the latter case applies to you, you can just go ahead and omit adaptor field entirely: here the fields are complete to show you a full example with all present fields.

metadataKeys is a list of metadata keys that need to be watched for, ignoring the oned that don't have them, although keep in mind that, as of now, only one is supported: if you write multiple metadata keys to watch, only the first one will be kept.

Under serviceRegistry you will need to specify the service registry that you want to be polled/watched.

Finally, remember that CLI flags will override any options defined in the configuration file: for example, if your configuration file includes pollInterval: 25 but launch the program with --interval 50, the former will be completely ignored.

Examples

With Service Directory

In the following example, the CN-WAN Reader watches changes in Google Cloud Service Directory with the following requirements:

  • The allowed services have at least the cnwan.io/traffic-profile key in their metadata
  • The project is called my-project
  • The region is us-west2
  • Service account is placed inside path/to/creds folder
  • The name of the service account file is serv-acc.json
  • The endpoint of the adaptor is the default one (http://localhost:80/cnwan/events). In such a case there is no need to use the --adaptor-api flag, but here it is included for clarity.
  • Interval between two watches is 10 seconds
cnwan-reader sd \
--service-account /path/to/the/service-account.json \
--project my-project \
--region us-west2 \
--metadata-key cnwan.io/traffic-profile \
--adaptor-api localhost/cnwan/events \
--interval 10

You can also use a configuration file to do that. Set the configuration file as this:

adaptor: localhost:80/cnwan
metadataKeys:
  - cnwan.io/traffic-profile
serviceRegistry:
  gcpServiceDirectory:
    pollInterval: 10
    region: us-west2
    projectID: my-project
    serviceAccountPath: /path/to/the/service-account.json

Execute the following command:

cnwan-reader servicedirectory --conf /path/to/configuration/file.yaml

or just:

cnwan-reader --conf /path/to/configuration/file.yaml

With Cloud Map

In the following example, the CN-WAN Reader watches changes in AWS Cloud Map with the following requirements:

  • The allowed services have at least the cnwan.io/traffic-profile key in their metadata
  • The region is us-west-2
  • The credentials file is in $HOME/.aws/credentials, so there is no need to use the --credentials-path flag.
  • The endpoint of the adaptor is the default one (http://localhost:80/cnwan/events). In such a case there is no need to use the --adaptor-api flag, but here it is included for clarity.
  • Interval between two watches is 10 seconds

The command below assumes you want to use the default aws profile: run the following command prior to running cnwan reader if you want to use another one:

export AWS_PROFILE=your_profile
cnwan-reader poll cloudmap \
--region us-west-2 \
--metadata-keys cnwan.io/traffic-profile \
--adaptor-api localhost/cnwan/events \
--interval 10

You can also use a configuration file to do that. Set the configuration file as:

...
serviceRegistry:
  awsCloudMap:
    region: us-west-2
    pollInterval: 10

The file has been truncated with just the relevant parts, follow the sections above or the previous example to get the rest of the file.

Execute the following command:

cnwan-reader poll cloudmap --conf /path/to/configuration/file.yaml

or just:

cnwan-reader --conf /path/to/configuration/file.yaml

Using tags

The default behavior of the CN-WAN Reader is to parse attributes on service instances. This behavior can be changed with --with-tags, which will tell the CN-WAN Reader to look for tags on services instead of attributes on instances.

This won't change how data is sent to the adaptor but only how it is searched and parsed on Cloud Map: if you store your metadata as attributes you may continue to use the cloudmap command as always; but if you register relevant metadata as tags -- i.e. if you register services with the CN-WAN Operator, then we recommend you to use --with-tags.

With etcd

In the following example, the CN-WAN Reader watches changes in etcd with the following requirements:

  • The allowed services have at least the cnwan.io/traffic-profile key in their metadata.
  • Username is admin and password s5B7&$n_12C.
  • There is only one etcd node, on address 10.11.12.13 on default port (2379).
  • The service registry has prefix /service-registry/
  • The endpoint of the adaptor is the default one (http://localhost:80/cnwan/events). In such a case there is no need to use the --adaptor-api flag, but here it is included for clarity.
cnwan-reader watch etcd \
--metadata-keys cnwan.io/traffic-profile \
--adaptor-api localhost/cnwan/events \
--username admin \
--password s5B7&$n_12C \
--endpoints 10.11.12.13:2379
--prefix /service-registry/