nova/doc/source/admin/vendordata.rst
Adam Spiers d47f1db49e Switch some GitHub URLs to point to opendev.org
Also update some outdated URLs at the same time, e.g. defcore is now
interop.

Unfortunately unlike GitHub, gitea doesn't yet support URLs with
shortened SHA1s; however this is being worked on:

    https://github.com/go-gitea/gitea/issues/6450

Change-Id: I6e6b63619f1138cc961b61be548453361d01f73c
2019-08-19 21:08:27 +01:00

7.1 KiB

Vendordata

Note

This section provides deployment information about the vendordata feature. For end-user information about the vendordata feature and instance metadata in general, refer to the user guide </user/metadata>.

The vendordata feature provides a way to pass vendor or deployment-specific information to instances. This can be accessed by users using the metadata service </admin/metadata-service> or with config drives </admin/config-drive>.

There are two vendordata modules provided with nova: StaticJSON and DynamicJSON.

StaticJSON

The StaticJSON module includes the contents of a static JSON file loaded from disk. This can be used for things which don't change between instances, such as the location of the corporate puppet server. It is the default provider.

Configuration

The service you must configure to enable the StaticJSON vendordata module depends on how guests are accessing vendordata. If using the metadata service, configuration applies to either nova-api or nova-api-metadata, depending on the deployment, while if using config drives, configuration applies to nova-compute. However, configuration is otherwise the same and the following options apply:

  • :oslo.configapi.vendordata_providers
  • :oslo.configapi.vendordata_jsonfile_path

Refer to the metadata service </admin/metadata-service> and config drive </admin/config-drive> documentation for more information on how to configure the required services.

DynamicJSON

The DynamicJSON module can make a request to an external REST service to determine what metadata to add to an instance. This is how we recommend you generate things like Active Directory tokens which change per instance.

When used, the DynamicJSON module will make a request to any REST services listed in the :oslo.configapi.vendordata_dynamic_targets configuration option. There can be more than one of these but note that they will be queried once per metadata request from the instance which can mean a lot of traffic depending on your configuration and the configuration of the instance.

The following data is passed to your REST service as a JSON encoded POST:

Key Description
project-id The ID of the project that owns this instance.
instance-id The UUID of this instance.
image-id The ID of the image used to boot this instance.
user-data As specified by the user at boot time.
hostname The hostname of the instance.
metadata As specified by the user at boot time.

Metadata fetched from the REST service will appear in the metadata service at a new file called vendordata2.json, with a path (either in the metadata service URL or in the config drive) like this:

openstack/latest/vendor_data2.json

For each dynamic target, there will be an entry in the JSON file named after that target. For example:

{
    "testing": {
        "value1": 1,
        "value2": 2,
        "value3": "three"
    }
}

The novajoin project provides a dynamic vendordata service to manage host instantiation in an IPA server.

Deployment considerations

Nova provides authentication to external metadata services in order to provide some level of certainty that the request came from nova. This is done by providing a service token with the request -- you can then just deploy your metadata service with the keystone authentication WSGI middleware. This is configured using the keystone authentication parameters in the :oslo.configvendordata_dynamic_auth configuration group.

Configuration

As with StaticJSON, the service you must configure to enable the DynamicJSON vendordata module depends on how guests are accessing vendordata. If using the metadata service, configuration applies to either nova-api or nova-api-metadata, depending on the deployment, while if using config drives, configuration applies to nova-compute. However, configuration is otherwise the same and the following options apply:

  • :oslo.configapi.vendordata_providers
  • :oslo.configapi.vendordata_dynamic_ssl_certfile
  • :oslo.configapi.vendordata_dynamic_connect_timeout
  • :oslo.configapi.vendordata_dynamic_read_timeout
  • :oslo.configapi.vendordata_dynamic_failure_fatal
  • :oslo.configapi.vendordata_dynamic_targets

Refer to the metadata service </admin/metadata-service> and config drive </admin/config-drive> documentation for more information on how to configure the required services.

In addition, there are also many options related to authentication. These are provided by keystone <> but are listed below for completeness:

  • :oslo.configvendordata_dynamic_auth.cafile
  • :oslo.configvendordata_dynamic_auth.certfile
  • :oslo.configvendordata_dynamic_auth.keyfile
  • :oslo.configvendordata_dynamic_auth.insecure
  • :oslo.configvendordata_dynamic_auth.timeout
  • :oslo.configvendordata_dynamic_auth.collect_timing
  • :oslo.configvendordata_dynamic_auth.split_loggers
  • :oslo.configvendordata_dynamic_auth.auth_type
  • :oslo.configvendordata_dynamic_auth.auth_section
  • :oslo.configvendordata_dynamic_auth.auth_url
  • :oslo.configvendordata_dynamic_auth.system_scope
  • :oslo.configvendordata_dynamic_auth.domain_id
  • :oslo.configvendordata_dynamic_auth.domain_name
  • :oslo.configvendordata_dynamic_auth.project_id
  • :oslo.configvendordata_dynamic_auth.project_name
  • :oslo.configvendordata_dynamic_auth.project_domain_id
  • :oslo.configvendordata_dynamic_auth.project_domain_name
  • :oslo.configvendordata_dynamic_auth.trust_id
  • :oslo.configvendordata_dynamic_auth.default_domain_id
  • :oslo.configvendordata_dynamic_auth.default_domain_name
  • :oslo.configvendordata_dynamic_auth.user_id
  • :oslo.configvendordata_dynamic_auth.username
  • :oslo.configvendordata_dynamic_auth.user_domain_id
  • :oslo.configvendordata_dynamic_auth.user_domain_name
  • :oslo.configvendordata_dynamic_auth.password
  • :oslo.configvendordata_dynamic_auth.tenant_id
  • :oslo.configvendordata_dynamic_auth.tenant_name

Refer to the keystone documentation </configuration/index.html> for information on configuring these.

References