Validation

`vespa.validation`

Validation of Vespa Cloud names for tenant, application and instance, and of the name of an application package.

The Vespa Cloud rules implemented here mirror the ones enforced by the controller in com.yahoo.vespa.hosted.controller.api.identifiers (Identifier, TenantId, ApplicationId and InstanceId):

Must start with a lowercase letter.
May only contain lowercase letters, digits and dashes.
No double-dashes, and may not end with a dash.
At most 40 characters (20 if the tenant still supports legacy endpoints).
api is reserved for all three, and default is reserved for tenant and application names (but is the default instance name, hence allowed for instances).
Instance names ending in -t are reserved for tester instances.

The controller expresses the character rules as ^(?=.{1,40}$)[a-z](-?[a-z0-9]+)*$. :data:NAME_PATTERN is an equivalent, but unambiguous, formulation of the same language, with the length check done separately to avoid the exponential backtracking that the nested quantifiers of the original would allow.

These rules apply to names that are given to Vespa Cloud. The name of an application package is a separate, more permissive thing — see :func:validate_application_package_name.

`validate_tenant_name(name)`

Validate a Vespa Cloud tenant name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The tenant name to validate.	required

Returns:

Name	Type	Description
`str`	`str`	The validated tenant name, unchanged.

Raises:

Type	Description
`ValueError`	If the name is not a valid tenant name.

Example

from vespa.validation import validate_tenant_name

validate_tenant_name("my-tenant")
'my-tenant'

`validate_application_name(name, legacy_endpoints=False)`

Validate a Vespa Cloud application name.

Parameters:

Name	Type	Description	Default
`name`	`str`	The application name to validate.	required
`legacy_endpoints`	`bool`	Set to True if the tenant still supports legacy (level 7 routing) endpoints, in which case the name may contain no more than 20 characters. Defaults to False.	`False`

Returns:

Name	Type	Description
`str`	`str`	The validated application name, unchanged.

Raises:

Type	Description
`ValueError`	If the name is not a valid application name.

Example

from vespa.validation import validate_application_name

validate_application_name("my-app")
'my-app'

`validate_instance_name(name)`

Validate a Vespa Cloud application instance name.

Note that default is a valid instance name, and that instance names ending in -t are reserved for tester instances.

Parameters:

Name	Type	Description	Default
`name`	`str`	The instance name to validate.	required

Returns:

Name	Type	Description
`str`	`str`	The validated instance name, unchanged.

Raises:

Type	Description
`ValueError`	If the name is not a valid instance name.

Example

from vespa.validation import validate_instance_name

validate_instance_name("default")
'default'

`validate_application_package_name(name)`

Validate the name of an :class:vespa.package.ApplicationPackage.

An application package name is not a Vespa Cloud application name — the Vespa Cloud tenant, application and instance names are given to :class:vespa.deployment.VespaCloud separately, and validated there — so the Vespa Cloud rules deliberately do not apply here, and self-hosted applications are free to use underscores. The name must, however, be usable for what pyvespa derives from it:

The default schema name, which is a Vespa identifier ([a-zA-Z_][a-zA-Z0-9_]*) once dashes are replaced by underscores, hence the leading letter.
The <name>_container and <name>_content cluster ids, which are xsd:NCName in services.xml, and which end up verbatim in Vespa Cloud endpoint names (where only underscores are translated, to dashes), hence lowercase only and the length limit.
The Docker container name used by :class:vespa.deployment.VespaDocker.

Parameters:

Name	Type	Description	Default
`name`	`str`	The application package name to validate.	required

Returns:

Name	Type	Description
`str`	`str`	The validated name, unchanged.

Raises:

Type	Description
`ValueError`	If the name is not a valid application package name.

Example

from vespa.validation import validate_application_package_name

validate_application_package_name("my_app")
'my_app'

`to_vespa_identifier(name)`

Convert a name to a Vespa identifier.

Vespa identifiers, such as schema and document type names, may contain underscores but not dashes, so dashes are replaced by underscores. This is the inverse of the controller's Identifier.toDns().

Parameters:

Name	Type	Description	Default
`name`	`str`	The name to convert.	required

Returns:

Name	Type	Description
`str`	`str`	The name with dashes replaced by underscores.

Example

from vespa.validation import to_vespa_identifier

to_vespa_identifier("my-app")
'my_app'

`validate_cloud_names(tenant=None, application=None, instance=None, legacy_endpoints=False)`

Validate any combination of Vespa Cloud tenant, application and instance names.

Arguments that are None are not validated.

Parameters:

Name	Type	Description	Default
`tenant`	`str`	Tenant name. Defaults to None.	`None`
`application`	`str`	Application name. Defaults to None.	`None`
`instance`	`str`	Instance name. Defaults to None.	`None`
`legacy_endpoints`	`bool`	Whether the tenant supports legacy endpoints, which limits the application name to 20 characters. Defaults to False.	`False`

Raises:

Type	Description
`ValueError`	If any of the given names is invalid.