cli: add cloud-init query subcommand to query instance metadata

Cloud-init caches any cloud metadata crawled during boot in the file
/run/cloud-init/instance-data.json. Cloud-init also standardizes some of
that metadata across all clouds. The command 'cloud-init query' surfaces a
simple CLI to query or format any cached instance metadata so that scripts
or end-users do not have to write tools to crawl metadata themselves.

Since 'cloud-init query' is runnable by non-root users, redact any
sensitive data from instance-data.json and provide a root-readable
unredacted instance-data-sensitive.json. Datasources can now define a
sensitive_metadata_keys tuple which will redact any matching keys
which could contain passwords or credentials from instance-data.json.

Also add the following standardized 'v1' instance-data.json keys:
  - user_data: The base64encoded user-data provided at instance launch
  - vendor_data: Any vendor_data provided to the instance at launch
  - underscore_delimited versions of existing hyphenated keys:
    instance_id, local_hostname, availability_zone, cloud_name

4 files changed, 388 insertions, 163 deletions

diff --git a/doc/rtd/index.rst b/doc/rtd/index.rst
index de67f361..20a99a30 100644
--- a/doc/rtd/index.rst
+++ b/doc/rtd/index.rst
@@ -31,6 +31,7 @@ initialization of a cloud instance.
    topics/capabilities.rst
    topics/availability.rst
    topics/format.rst
+   topics/instancedata.rst
    topics/dir_layout.rst
    topics/examples.rst
    topics/boot.rst
diff --git a/doc/rtd/topics/capabilities.rst b/doc/rtd/topics/capabilities.rst
index 2d8e2538..0d8b8947 100644
--- a/doc/rtd/topics/capabilities.rst
+++ b/doc/rtd/topics/capabilities.rst
@@ -18,7 +18,7 @@ User configurability
 
     User-data can be given by the user at instance launch time. See
     :ref:`user_data_formats` for acceptable user-data content.
-    
+
 
 This is done via the ``--user-data`` or ``--user-data-file`` argument to
 ec2-run-instances for example.
@@ -53,10 +53,9 @@ system:
 
   % cloud-init --help
   usage: cloud-init [-h] [--version] [--file FILES]
-
                     [--debug] [--force]
-                    {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
-                    ...
+                    {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
+                                                         ...
 
   optional arguments:
     -h, --help            show this help message and exit
@@ -68,17 +67,19 @@ system:
                           your own risk)
 
   Subcommands:
-    {init,modules,single,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
+    {init,modules,single,query,dhclient-hook,features,analyze,devel,collect-logs,clean,status}
       init                initializes cloud-init and performs initial modules
       modules             activates modules using a given configuration key
       single              run a single module
+      query               Query instance metadata from the command line
       dhclient-hook       run the dhclient hookto record network info
       features            list defined features
       analyze             Devel tool: Analyze cloud-init logs and data
       devel               Run development tools
       collect-logs        Collect and tar all cloud-init debug info
-      clean               Remove logs and artifacts so cloud-init can re-run.
-      status              Report cloud-init status or wait on completion.
+      clean               Remove logs and artifacts so cloud-init can re-run
+      status              Report cloud-init status or wait on completion
+
 
 CLI Subcommand details
 ======================
@@ -104,8 +105,8 @@ cloud-init status
 Report whether cloud-init is running, done, disabled or errored. Exits
 non-zero if an error is detected in cloud-init.
 
- * **--long**: Detailed status information.
- * **--wait**: Block until cloud-init completes.
+* **--long**: Detailed status information.
+* **--wait**: Block until cloud-init completes.
 
 .. code-block:: shell-session
 
@@ -143,6 +144,68 @@ Logs collected are:
  * journalctl output
  * /var/lib/cloud/instance/user-data.txt
 
+.. _cli_query:
+
+cloud-init query
+------------------
+Query standardized cloud instance metadata crawled by cloud-init and stored
+in ``/run/cloud-init/instance-data.json``. This is a convenience command-line
+interface to reference any cached configuration metadata that cloud-init
+crawls when booting the instance. See :ref:`instance_metadata` for more info.
+
+* **--all**: Dump all available instance data as json which can be queried.
+* **--instance-data**: Optional path to a different instance-data.json file to
+  source for queries.
+* **--list-keys**: List available query keys from cached instance data.
+
+.. code-block:: shell-session
+
+  # List all top-level query keys available (includes standardized aliases)
+  % cloud-init query --list-keys
+  availability_zone
+  base64_encoded_keys
+  cloud_name
+  ds
+  instance_id
+  local_hostname
+  region
+  v1
+
+* **<varname>**: A dot-delimited variable path into the instance-data.json
+   object.
+
+.. code-block:: shell-session
+
+  # Query cloud-init standardized metadata on any cloud
+  % cloud-init query v1.cloud_name
+  aws  # or openstack, azure, gce etc.
+
+  # Any standardized instance-data under a <v#> key is aliased as a top-level
+  # key for convenience.
+  % cloud-init query cloud_name
+  aws  # or openstack, azure, gce etc.
+
+  # Query datasource-specific metadata on EC2
+  % cloud-init query ds.meta_data.public_ipv4
+
+* **--format** A string that will use jinja-template syntax to render a string
+   replacing
+
+.. code-block:: shell-session
+
+  # Generate a custom hostname fqdn based on instance-id, cloud and region
+  % cloud-init query --format 'custom-{{instance_id}}.{{region}}.{{v1.cloud_name}}.com'
+  custom-i-0e91f69987f37ec74.us-east-2.aws.com
+
+
+.. note::
+  The standardized instance data keys under **v#** are guaranteed not to change
+  behavior or format. If using top-level convenience aliases for any
+  standardized instance data keys, the most value (highest **v#**) of that key
+  name is what is reported as the top-level value. So these aliases act as a
+  'latest'.
+
+
 .. _cli_analyze:
 
 cloud-init analyze
@@ -150,10 +213,10 @@ cloud-init analyze
 Get detailed reports of where cloud-init spends most of its time. See
 :ref:`boot_time_analysis` for more info.
 
- * **blame** Report ordered by most costly operations.
- * **dump** Machine-readable JSON dump of all cloud-init tracked events.
- * **show** show time-ordered report of the cost of operations during each
-   boot stage.
+* **blame** Report ordered by most costly operations.
+* **dump** Machine-readable JSON dump of all cloud-init tracked events.
+* **show** show time-ordered report of the cost of operations during each
+  boot stage.
 
 .. _cli_devel:
 
@@ -182,8 +245,8 @@ cloud-init clean
 Remove cloud-init artifacts from /var/lib/cloud and optionally reboot the
 machine to so cloud-init re-runs all stages as it did on first boot.
 
- * **--logs**: Optionally remove /var/log/cloud-init*log files.
- * **--reboot**: Reboot the system after removing artifacts.
+* **--logs**: Optionally remove /var/log/cloud-init*log files.
+* **--reboot**: Reboot the system after removing artifacts.
 
 .. _cli_init:
 
@@ -195,7 +258,7 @@ Can be run on the commandline, but is generally gated to run only once
 due to semaphores in **/var/lib/cloud/instance/sem/** and
 **/var/lib/cloud/sem**.
 
- * **--local**: Run *init-local* stage instead of *init*.
+* **--local**: Run *init-local* stage instead of *init*.
 
 .. _cli_modules:
 
@@ -210,8 +273,8 @@ declared to run in various boot stages in the file
 commandline, but each module is gated to run only once due to semaphores
 in ``/var/lib/cloud/``.
 
- * **--mode (init|config|final)**: Run *modules:init*, *modules:config* or
-   *modules:final* cloud-init stages. See :ref:`boot_stages` for more info.
+* **--mode (init|config|final)**: Run *modules:init*, *modules:config* or
+  *modules:final* cloud-init stages. See :ref:`boot_stages` for more info.
 
 .. _cli_single:
 
@@ -221,9 +284,9 @@ Attempt to run a single named cloud config module.  The following example
 re-runs the cc_set_hostname module ignoring the module default frequency
 of once-per-instance:
 
- * **--name**: The cloud-config module name to run
- * **--frequency**: Optionally override the declared module frequency
-   with one of (always|once-per-instance|once)
+* **--name**: The cloud-config module name to run
+* **--frequency**: Optionally override the declared module frequency
+  with one of (always|once-per-instance|once)
 
 .. code-block:: shell-session
 
diff --git a/doc/rtd/topics/datasources.rst b/doc/rtd/topics/datasources.rst
index 14432e65..e34f145c 100644
--- a/doc/rtd/topics/datasources.rst
+++ b/doc/rtd/topics/datasources.rst
@@ -17,146 +17,10 @@ own way) internally a datasource abstract class was created to allow for a
 single way to access the different cloud systems methods to provide this data
 through the typical usage of subclasses.
 
-
-.. _instance_metadata:
-
-instance-data
--------------
-For reference, cloud-init stores all the metadata, vendordata and userdata
-provided by a cloud in a json blob at ``/run/cloud-init/instance-data.json``.
-While the json contains datasource-specific keys and names, cloud-init will
-maintain a minimal set of standardized keys that will remain stable on any
-cloud. Standardized instance-data keys will be present under a "v1" key.
-Any datasource metadata cloud-init consumes will all be present under the
-"ds" key.
-
-Below is an instance-data.json example from an OpenStack instance:
-
-.. sourcecode:: json
-
-  {
-   "base64-encoded-keys": [
-    "ds/meta-data/random_seed",
-    "ds/user-data"
-   ],
-   "ds": {
-    "ec2_metadata": {
-     "ami-id": "ami-0000032f",
-     "ami-launch-index": "0",
-     "ami-manifest-path": "FIXME",
-     "block-device-mapping": {
-      "ami": "vda",
-      "ephemeral0": "/dev/vdb",
-      "root": "/dev/vda"
-     },
-     "hostname": "xenial-test.novalocal",
-     "instance-action": "none",
-     "instance-id": "i-0006e030",
-     "instance-type": "m1.small",
-     "local-hostname": "xenial-test.novalocal",
-     "local-ipv4": "10.5.0.6",
-     "placement": {
-      "availability-zone": "None"
-     },
-     "public-hostname": "xenial-test.novalocal",
-     "public-ipv4": "10.245.162.145",
-     "reservation-id": "r-fxm623oa",
-     "security-groups": "default"
-    },
-    "meta-data": {
-     "availability_zone": null,
-     "devices": [],
-     "hostname": "xenial-test.novalocal",
-     "instance-id": "3e39d278-0644-4728-9479-678f9212d8f0",
-     "launch_index": 0,
-     "local-hostname": "xenial-test.novalocal",
-     "name": "xenial-test",
-     "project_id": "e0eb2d2538814...",
-     "random_seed": "A6yPN...",
-     "uuid": "3e39d278-0644-4728-9479-678f92..."
-    },
-    "network_json": {
-     "links": [
-      {
-       "ethernet_mac_address": "fa:16:3e:7d:74:9b",
-       "id": "tap9ca524d5-6e",
-       "mtu": 8958,
-       "type": "ovs",
-       "vif_id": "9ca524d5-6e5a-4809-936a-6901..."
-      }
-     ],
-     "networks": [
-      {
-       "id": "network0",
-       "link": "tap9ca524d5-6e",
-       "network_id": "c6adfc18-9753-42eb-b3ea-18b57e6b837f",
-       "type": "ipv4_dhcp"
-      }
-     ],
-     "services": [
-      {
-       "address": "10.10.160.2",
-       "type": "dns"
-      }
-     ]
-    },
-    "user-data": "I2Nsb3VkLWNvbmZpZ...",
-    "vendor-data": null
-   },
-   "v1": {
-    "availability-zone": null,
-    "cloud-name": "openstack",
-    "instance-id": "3e39d278-0644-4728-9479-678f9212d8f0",
-    "local-hostname": "xenial-test",
-    "region": null
-   }
-  }
-
- 
-As of cloud-init v. 18.4, any values present in
-``/run/cloud-init/instance-data.json`` can be used in cloud-init user data
-scripts or cloud config data. This allows consumers to use cloud-init's
-vendor-neutral, standardized metadata keys as well as datasource-specific
-content for any scripts or cloud-config modules they are using.
-
-To use instance-data.json values in scripts and **#config-config** files the
-user-data will need to contain the following header as the first line **## template: jinja**. Cloud-init will source all variables defined in
-``/run/cloud-init/instance-data.json`` and allow scripts or cloud-config files 
-to reference those paths. Below are two examples::
-
- * Cloud config calling home with the ec2 public hostname and avaliability-zone
-    ```
-    ## template: jinja
-    #cloud-config
-    runcmd:
-        - echo 'EC2 public hostname allocated to instance: {{ ds.meta_data.public_hostname }}' > /tmp/instance_metadata
-        - echo 'EC2 avaiability zone: {{ v1.availability_zone }}' >> /tmp/instance_metadata 
-        - curl -X POST -d '{"hostname": "{{ds.meta_data.public_hostname }}", "availability-zone": "{{ v1.availability_zone }}"}'  https://example.com.com
-    ```
-
- * Custom user script performing different operations based on region
-    ```
-    ## template: jinja
-    #!/bin/bash
-    {% if v1.region == 'us-east-2' -%}
-    echo 'Installing custom proxies for {{ v1.region }}
-    sudo apt-get install my-xtra-fast-stack
-    {%- endif %}
-    ...
-
-    ```
-
-.. note::
-  Trying to reference jinja variables that don't exist in
-  instance-data.json will result in warnings in ``/var/log/cloud-init.log``
-  and the following string in your rendered user-data:
-  ``CI_MISSING_JINJA_VAR/<your_varname>``.
-  
-.. note::
-  To save time designing your user-data for a specific cloud's
-  instance-data.json, use the 'render' cloud-init command on an
-  instance booted on your favorite cloud. See :ref:`cli_devel` for more
-  information.
+Any metadata processed by cloud-init's datasources is persisted as
+``/run/cloud0-init/instance-data.json``. Cloud-init provides tooling
+to quickly introspect some of that data. See :ref:`instance_metadata` for
+more information.
 
 
 Datasource API
@@ -196,14 +60,14 @@ The current interface that a datasource object must provide is the following:
     # or does not exist)
     def device_name_to_device(self, name)
 
-    # gets the locale string this instance should be applying 
+    # gets the locale string this instance should be applying
     # which typically used to adjust the instances locale settings files
     def get_locale(self)
 
     @property
     def availability_zone(self)
 
-    # gets the instance id that was assigned to this instance by the 
+    # gets the instance id that was assigned to this instance by the
     # cloud provider or when said instance id does not exist in the backing
     # metadata this will return 'iid-datasource'
     def get_instance_id(self)
diff --git a/doc/rtd/topics/instancedata.rst b/doc/rtd/topics/instancedata.rst
new file mode 100644
index 00000000..634e1807
--- /dev/null
+++ b/doc/rtd/topics/instancedata.rst
@@ -0,0 +1,297 @@
+.. _instance_metadata:
+
+*****************
+Instance Metadata
+*****************
+
+What is a instance data?
+========================
+
+Instance data is the collection of all configuration data that cloud-init
+processes to configure the instance. This configuration typically
+comes from any number of sources:
+
+* cloud-provided metadata services (aka metadata)
+* custom config-drive attached to the instance
+* cloud-config seed files in the booted cloud image or distribution
+* vendordata provided from files or cloud metadata services
+* userdata provided at instance creation
+
+Each cloud provider presents unique configuration metadata in different
+formats to the instance. Cloud-init provides a cache of any crawled metadata
+as well as a versioned set of standardized instance data keys which it makes
+available on all platforms.
+
+Cloud-init produces a simple json object in
+``/run/cloud-init/instance-data.json`` which represents standardized and
+versioned representation of the metadata it consumes during initial boot. The
+intent is to provide the following benefits to users or scripts on any system
+deployed with cloud-init:
+
+* simple static object to query to obtain a instance's metadata
+* speed: avoid costly network transactions for metadata that is already cached
+  on the filesytem
+* reduce need to recrawl metadata services for static metadata that is already
+  cached
+* leverage cloud-init's best practices for crawling cloud-metadata services
+* avoid rolling unique metadata crawlers on each cloud platform to get
+  metadata configuration values
+
+Cloud-init stores any instance data processed in the following files:
+
+* ``/run/cloud-init/instance-data.json``: world-readable json containing
+  standardized keys, sensitive keys redacted
+* ``/run/cloud-init/instance-data-sensitive.json``: root-readable unredacted
+  json blob
+* ``/var/lib/cloud/instance/user-data.txt``: root-readable sensitive raw
+  userdata
+* ``/var/lib/cloud/instance/vendor-data.txt``: root-readable sensitive raw
+  vendordata
+
+Cloud-init redacts any security sensitive content from instance-data.json,
+stores ``/run/cloud-init/instance-data.json`` as a world-readable json file.
+Because user-data and vendor-data can contain passwords both of these files
+are readonly for *root* as well. The *root* user can also read
+``/run/cloud-init/instance-data-sensitive.json`` which is all instance data
+from instance-data.json as well as unredacted sensitive content.
+
+
+Format of instance-data.json
+============================
+
+The instance-data.json and instance-data-sensitive.json files are well-formed
+JSON and record the set of keys and values for any metadata processed by
+cloud-init. Cloud-init standardizes the format for this content so that it
+can be generalized across different cloud platforms.
+
+There are three basic top-level keys:
+
+* **base64_encoded_keys**: A list of forward-slash delimited key paths into
+  the instance-data.json object whose value is base64encoded for json
+  compatibility. Values at these paths should be decoded to get the original
+  value.
+
+* **sensitive_keys**: A list of forward-slash delimited key paths into
+  the instance-data.json object whose value is considered by the datasource as
+  'security sensitive'. Only the keys listed here will be redacted from
+  instance-data.json for non-root users.
+
+* **ds**: Datasource-specific metadata crawled for the specific cloud
+  platform. It should closely represent the structure of the cloud metadata
+  crawled. The structure of content and details provided are entirely
+  cloud-dependent. Mileage will vary depending on what the cloud exposes.
+  The content exposed under the 'ds' key is currently **experimental** and
+  expected to change slightly in the upcoming cloud-init release.
+
+* **v1**: Standardized cloud-init metadata keys, these keys are guaranteed to
+  exist on all cloud platforms. They will also retain their current behavior
+  and format and will be carried forward even if cloud-init introduces a new
+  version of standardized keys with **v2**.
+
+The standardized keys present:
+
++----------------------+-----------------------------------------------+---------------------------+
+|  Key path            | Description                                   | Examples                  |
++======================+===============================================+===========================+
+| v1.cloud_name        | The name of the cloud provided by metadata    | aws, openstack, azure,    |
+|                      | key 'cloud-name' or the cloud-init datasource | configdrive, nocloud,     |
+|                      | name which was discovered.                    | ovf, etc.                 |
++----------------------+-----------------------------------------------+---------------------------+
+| v1.instance_id       | Unique instance_id allocated by the cloud     | i-<somehash>              |
++----------------------+-----------------------------------------------+---------------------------+
+| v1.local_hostname    | The internal or local hostname of the system  | ip-10-41-41-70,           |
+|                      |                                               | <user-provided-hostname>  |
++----------------------+-----------------------------------------------+---------------------------+
+| v1.region            | The physical region/datacenter in which the   | us-east-2                 |
+|                      | instance is deployed                          |                           |
++----------------------+-----------------------------------------------+---------------------------+
+| v1.availability_zone | The physical availability zone in which the   | us-east-2b, nova, null    |
+|                      | instance is deployed                          |                           |
++----------------------+-----------------------------------------------+---------------------------+
+
+
+Below is an example of ``/run/cloud-init/instance_data.json`` on an EC2
+instance:
+
+.. sourcecode:: json
+
+  {
+   "base64_encoded_keys": [],
+   "sensitive_keys": [],
+   "ds": {
+    "meta_data": {
+     "ami-id": "ami-014e1416b628b0cbf",
+     "ami-launch-index": "0",
+     "ami-manifest-path": "(unknown)",
+     "block-device-mapping": {
+      "ami": "/dev/sda1",
+      "ephemeral0": "sdb",
+      "ephemeral1": "sdc",
+      "root": "/dev/sda1"
+     },
+     "hostname": "ip-10-41-41-70.us-east-2.compute.internal",
+     "instance-action": "none",
+     "instance-id": "i-04fa31cfc55aa7976",
+     "instance-type": "t2.micro",
+     "local-hostname": "ip-10-41-41-70.us-east-2.compute.internal",
+     "local-ipv4": "10.41.41.70",
+     "mac": "06:b6:92:dd:9d:24",
+     "metrics": {
+      "vhostmd": "<?xml version=\"1.0\" encoding=\"UTF-8\"?>"
+     },
+     "network": {
+      "interfaces": {
+       "macs": {
+	"06:b6:92:dd:9d:24": {
+	 "device-number": "0",
+	 "interface-id": "eni-08c0c9fdb99b6e6f4",
+	 "ipv4-associations": {
+	  "18.224.22.43": "10.41.41.70"
+	 },
+	 "local-hostname": "ip-10-41-41-70.us-east-2.compute.internal",
+	 "local-ipv4s": "10.41.41.70",
+	 "mac": "06:b6:92:dd:9d:24",
+	 "owner-id": "437526006925",
+	 "public-hostname": "ec2-18-224-22-43.us-east-2.compute.amazonaws.com",
+	 "public-ipv4s": "18.224.22.43",
+	 "security-group-ids": "sg-828247e9",
+	 "security-groups": "Cloud-init integration test secgroup",
+	 "subnet-id": "subnet-282f3053",
+	 "subnet-ipv4-cidr-block": "10.41.41.0/24",
+	 "subnet-ipv6-cidr-blocks": "2600:1f16:b80:ad00::/64",
+	 "vpc-id": "vpc-252ef24d",
+	 "vpc-ipv4-cidr-block": "10.41.0.0/16",
+	 "vpc-ipv4-cidr-blocks": "10.41.0.0/16",
+	 "vpc-ipv6-cidr-blocks": "2600:1f16:b80:ad00::/56"
+	}
+       }
+      }
+     },
+     "placement": {
+      "availability-zone": "us-east-2b"
+     },
+     "profile": "default-hvm",
+     "public-hostname": "ec2-18-224-22-43.us-east-2.compute.amazonaws.com",
+     "public-ipv4": "18.224.22.43",
+     "public-keys": {
+      "cloud-init-integration": [
+       "ssh-rsa
+  AAAAB3NzaC1yc2EAAAADAQABAAABAQDSL7uWGj8cgWyIOaspgKdVy0cKJ+UTjfv7jBOjG2H/GN8bJVXy72XAvnhM0dUM+CCs8FOf0YlPX+Frvz2hKInrmRhZVwRSL129PasD12MlI3l44u6IwS1o/W86Q+tkQYEljtqDOo0a+cOsaZkvUNzUyEXUwz/lmYa6G4hMKZH4NBj7nbAAF96wsMCoyNwbWryBnDYUr6wMbjRR1J9Pw7Xh7WRC73wy4Va2YuOgbD3V/5ZrFPLbWZW/7TFXVrql04QVbyei4aiFR5n//GvoqwQDNe58LmbzX/xvxyKJYdny2zXmdAhMxbrpFQsfpkJ9E/H5w0yOdSvnWbUoG5xNGoOB
+  cloud-init-integration"
+      ]
+     },
+     "reservation-id": "r-06ab75e9346f54333",
+     "security-groups": "Cloud-init integration test secgroup",
+     "services": {
+      "domain": "amazonaws.com",
+      "partition": "aws"
+     }
+    }
+   },
+   "v1": {
+    "availability-zone": "us-east-2b",
+    "availability_zone": "us-east-2b",
+    "cloud-name": "aws",
+    "cloud_name": "aws",
+    "instance-id": "i-04fa31cfc55aa7976",
+    "instance_id": "i-04fa31cfc55aa7976",
+    "local-hostname": "ip-10-41-41-70",
+    "local_hostname": "ip-10-41-41-70",
+    "region": "us-east-2"
+   }
+  }
+
+
+Using instance-data
+===================
+
+As of cloud-init v. 18.4, any variables present in
+``/run/cloud-init/instance-data.json`` can be used in:
+
+* User-data scripts
+* Cloud config data
+* Command line interface via **cloud-init query** or
+  **cloud-init devel render**
+
+Many clouds allow users to provide user-data to an instance at
+the time the instance is launched. Cloud-init supports a number of
+:ref:`user_data_formats`.
+
+Both user-data scripts and **#cloud-config** data support jinja template
+rendering.
+When the first line of the provided user-data begins with,
+**## template: jinja** cloud-init will use jinja to render that file.
+Any instance-data-sensitive.json variables are surfaced as dot-delimited
+jinja template variables because cloud-config modules are run as 'root'
+user.
+
+
+Below are some examples of providing these types of user-data:
+
+* Cloud config calling home with the ec2 public hostname and avaliability-zone
+
+.. code-block:: shell-session
+
+  ## template: jinja
+  #cloud-config
+  runcmd:
+      - echo 'EC2 public hostname allocated to instance: {{
+        ds.meta_data.public_hostname }}' > /tmp/instance_metadata
+      - echo 'EC2 avaiability zone: {{ v1.availability_zone }}' >>
+        /tmp/instance_metadata
+      - curl -X POST -d '{"hostname": "{{ds.meta_data.public_hostname }}",
+        "availability-zone": "{{ v1.availability_zone }}"}'
+        https://example.com
+
+* Custom user-data script performing different operations based on region
+
+.. code-block:: shell-session
+
+   ## template: jinja
+   #!/bin/bash
+   {% if v1.region == 'us-east-2' -%}
+   echo 'Installing custom proxies for {{ v1.region }}
+   sudo apt-get install my-xtra-fast-stack
+   {%- endif %}
+   ...
+
+.. note::
+  Trying to reference jinja variables that don't exist in
+  instance-data.json will result in warnings in ``/var/log/cloud-init.log``
+  and the following string in your rendered user-data:
+  ``CI_MISSING_JINJA_VAR/<your_varname>``.
+
+Cloud-init also surfaces a commandline tool **cloud-init query** which can
+assist developers or scripts with obtaining instance metadata easily. See
+:ref:`cli_query` for more information.
+
+To cut down on keystrokes on the command line, cloud-init also provides
+top-level key aliases for any standardized ``v#`` keys present. The preceding
+``v1`` is not required of ``v1.var_name`` These aliases will represent the
+value of the highest versioned standard key. For example, ``cloud_name``
+value will be ``v2.cloud_name`` if both ``v1`` and ``v2`` keys are present in
+instance-data.json.
+The **query** command also publishes ``userdata`` and ``vendordata`` keys to
+the root user which will contain the decoded user and vendor data provided to
+this instance. Non-root users referencing userdata or vendordata keys will
+see only redacted values.
+
+.. code-block:: shell-session
+
+ # List all top-level instance-data keys available
+ % cloud-init query --list-keys
+
+ # Find your EC2 ami-id
+ % cloud-init query ds.metadata.ami_id
+
+ # Format your cloud_name and region using jinja template syntax
+ % cloud-init query --format 'cloud: {{ v1.cloud_name }} myregion: {{
+ % v1.region }}'
+
+.. note::
+  To save time designing a user-data template for a specific cloud's
+  instance-data.json, use the 'render' cloud-init command on an
+  instance booted on your favorite cloud. See :ref:`cli_devel` for more
+  information.
+
+.. vi: textwidth=78