Table Of Contents

Feedback

User Guide

First time using the AWS CLI? See the User Guide for help getting started.

[ aws . appmesh ]

create-virtual-node

Description

Creates a virtual node within a service mesh.

A virtual node acts as a logical pointer to a particular task group, such as an Amazon ECS service or a Kubernetes deployment. When you create a virtual node, you can specify the service discovery information for your task group.

Any inbound traffic that your virtual node expects should be specified as a listener . Any outbound traffic that your virtual node expects to reach should be specified as a backend .

The response metadata for your new virtual node contains the arn that is associated with the virtual node. Set this value (either the full ARN or the truncated resource name: for example, mesh/default/virtualNode/simpleapp ) as the APPMESH_VIRTUAL_NODE_NAME environment variable for your task group's Envoy proxy container in your task definition or pod spec. This is then mapped to the node.id and node.cluster Envoy parameters.

Note

If you require your Envoy stats or tracing to use a different name, you can override the node.cluster value that is set by APPMESH_VIRTUAL_NODE_NAME with the APPMESH_VIRTUAL_NODE_CLUSTER environment variable.

See also: AWS API Documentation

See 'aws help' for descriptions of global parameters.

Synopsis

  create-virtual-node
[--client-token <value>]
--mesh-name <value>
--spec <value>
[--tags <value>]
--virtual-node-name <value>
[--cli-input-json <value>]
[--generate-cli-skeleton <value>]

Options

--client-token (string)

Unique, case-sensitive identifier that you provide to ensure the idempotency of the request. Up to 36 letters, numbers, hyphens, and underscores are allowed.

--mesh-name (string)

The name of the service mesh to create the virtual node in.

--spec (structure)

The virtual node specification to apply.

JSON Syntax:

{
  "backends": [
    {
      "virtualService": {
        "virtualServiceName": "string"
      }
    }
    ...
  ],
  "listeners": [
    {
      "healthCheck": {
        "healthyThreshold": integer,
        "intervalMillis": long,
        "path": "string",
        "port": integer,
        "protocol": "http"|"tcp",
        "timeoutMillis": long,
        "unhealthyThreshold": integer
      },
      "portMapping": {
        "port": integer,
        "protocol": "http"|"tcp"
      }
    }
    ...
  ],
  "logging": {
    "accessLog": {
      "file": {
        "path": "string"
      }
    }
  },
  "serviceDiscovery": {
    "awsCloudMap": {
      "attributes": [
        {
          "key": "string",
          "value": "string"
        }
        ...
      ],
      "namespaceName": "string",
      "serviceName": "string"
    },
    "dns": {
      "hostname": "string"
    }
  }
}

--tags (list)

Optional metadata that you can apply to the virtual node to assist with categorization and organization. Each tag consists of a key and an optional value, both of which you define. Tag keys can have a maximum character length of 128 characters, and tag values can have a maximum length of 256 characters.

Shorthand Syntax:

key=string,value=string ...

JSON Syntax:

[
  {
    "key": "string",
    "value": "string"
  }
  ...
]

--virtual-node-name (string)

The name to use for the virtual node.

--cli-input-json (string) Performs service operation based on the JSON string provided. The JSON string follows the format provided by --generate-cli-skeleton. If other arguments are provided on the command line, the CLI values will override the JSON-provided values. It is not possible to pass arbitrary binary values using a JSON-provided value as the string will be taken literally.

--generate-cli-skeleton (string) Prints a JSON skeleton to standard output without sending an API request. If provided with no value or the value input, prints a sample input JSON that can be used as an argument for --cli-input-json. If provided with the value output, it validates the command inputs and returns a sample output JSON for that command.

See 'aws help' for descriptions of global parameters.

Examples

Example 1: To create a new virtual node that uses DNS for discovery

The following create-virtual-node example uses a JSON input file to create a virtual node that uses DNS for service discovery.

aws appmesh create-virtual-node \
    --cli-input-json file://create-virtual-node-dns.json

Contents of create-virtual-node-dns.json:

{
    "meshName": "app1",
    "spec": {
        "listeners": [
            {
                "portMapping": {
                    "port": 80,
                    "protocol": "http"
                }
            }
        ],
        "serviceDiscovery": {
            "dns": {
                "hostname": "serviceBv1.svc.cluster.local"
            }
        }
    },
    "virtualNodeName": "vnServiceBv1"
}

Output:

{
    "virtualNode": {
        "meshName": "app1",
        "metadata": {
            "arn": "arn:aws:appmesh:us-east-1:123456789012:mesh/app1/virtualNode/vnServiceBv1",
            "createdAt": 1563810019.874,
            "lastUpdatedAt": 1563810019.874,
            "uid": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
            "version": 1
        },
        "spec": {
            "listeners": [
                {
                    "portMapping": {
                        "port": 80,
                        "protocol": "http"
                    }
                }
            ],
            "serviceDiscovery": {
                "dns": {
                    "hostname": "serviceBv1.svc.cluster.local"
                }
            }
        },
        "status": {
            "status": "ACTIVE"
        },
        "virtualNodeName": "vnServiceBv1"
    }
}

Example 2: To create a new virtual node that uses AWS Cloud Map for discovery

The following create-virtual-node example uses a JSON input file to create a virtual node that uses AWS Cloud Map for service discovery.

aws appmesh create-virtual-node \
    --cli-input-json file://create-virtual-node-cloud-map.json

Contents of create-virtual-node-cloud-map.json:

{
    "meshName": "app1",
    "spec": {
        "backends": [
            {
                "virtualService": {
                    "virtualServiceName": "serviceA.svc.cluster.local"
                }
            }
        ],
        "listeners": [
            {
                "portMapping": {
                    "port": 80,
                    "protocol": "http"
                }
            }
        ],
        "serviceDiscovery": {
            "awsCloudMap": {
                "attributes": [
                    {
                        "key": "Environment",
                        "value": "Testing"
                    }
                ],
                "namespaceName": "namespace1",
                "serviceName": "serviceA"
            }
        }
    },
    "virtualNodeName": "vnServiceA"
}

Output:

{
    "virtualNode": {
        "meshName": "app1",
        "metadata": {
            "arn": "arn:aws:appmesh:us-east-1:123456789012:mesh/app1/virtualNode/vnServiceA",
            "createdAt": 1563810859.465,
            "lastUpdatedAt": 1563810859.465,
            "uid": "a1b2c3d4-5678-90ab-cdef-11111EXAMPLE",
            "version": 1
        },
        "spec": {
            "backends": [
                {
                    "virtualService": {
                        "virtualServiceName": "serviceA.svc.cluster.local"
                    }
                }
            ],
            "listeners": [
                {
                    "portMapping": {
                        "port": 80,
                        "protocol": "http"
                    }
                }
            ],
            "serviceDiscovery": {
                "awsCloudMap": {
                    "attributes": [
                        {
                            "key": "Environment",
                            "value": "Testing"
                        }
                    ],
                    "namespaceName": "namespace1",
                    "serviceName": "serviceA"
                }
            }
        },
        "status": {
            "status": "ACTIVE"
        },
        "virtualNodeName": "vnServiceA"
    }
}

For more information, see Virtual Nodes in the AWS App Mesh User Guide.

Output

virtualNode -> (structure)

The full description of your virtual node following the create call.

meshName -> (string)

The name of the service mesh that the virtual node resides in.

metadata -> (structure)

The associated metadata for the virtual node.

arn -> (string)

The full Amazon Resource Name (ARN) for the resource.

createdAt -> (timestamp)

The Unix epoch timestamp in seconds for when the resource was created.

lastUpdatedAt -> (timestamp)

The Unix epoch timestamp in seconds for when the resource was last updated.

uid -> (string)

The unique identifier for the resource.

version -> (long)

The version of the resource. Resources are created at version 1, and this version is incremented each time that they're updated.

spec -> (structure)

The specifications of the virtual node.

backends -> (list)

The backends that the virtual node is expected to send outbound traffic to.

(structure)

An object representing the backends that a virtual node is expected to send outbound traffic to.

virtualService -> (structure)

Specifies a virtual service to use as a backend for a virtual node.

virtualServiceName -> (string)

The name of the virtual service that is acting as a virtual node backend.

listeners -> (list)

The listeners that the virtual node is expected to receive inbound traffic from. Currently only one listener is supported per virtual node.

(structure)

An object representing a listener for a virtual node.

healthCheck -> (structure)

The health check information for the listener.

healthyThreshold -> (integer)

The number of consecutive successful health checks that must occur before declaring listener healthy.

intervalMillis -> (long)

The time period in milliseconds between each health check execution.

path -> (string)

The destination path for the health check request. This is required only if the specified protocol is HTTP. If the protocol is TCP, this parameter is ignored.

port -> (integer)

The destination port for the health check request. This port must match the port defined in the PortMapping for the listener.

protocol -> (string)

The protocol for the health check request.

timeoutMillis -> (long)

The amount of time to wait when receiving a response from the health check, in milliseconds.

unhealthyThreshold -> (integer)

The number of consecutive failed health checks that must occur before declaring a virtual node unhealthy.

portMapping -> (structure)

The port mapping information for the listener.

port -> (integer)

The port used for the port mapping.

protocol -> (string)

The protocol used for the port mapping.

logging -> (structure)

The inbound and outbound access logging information for the virtual node.

accessLog -> (structure)

The access log configuration for a virtual node.

file -> (structure)

The file object to send virtual node access logs to.

path -> (string)

The file path to write access logs to. You can use /dev/stdout to send access logs to standard out and configure your Envoy container to use a log driver, such as awslogs , to export the access logs to a log storage service such as Amazon CloudWatch Logs. You can also specify a path in the Envoy container's file system to write the files to disk.

Note

The Envoy process must have write permissions to the path that you specify here. Otherwise, Envoy fails to bootstrap properly.

serviceDiscovery -> (structure)

The service discovery information for the virtual node. If your virtual node does not expect ingress traffic, you can omit this parameter.

awsCloudMap -> (structure)

Specifies any AWS Cloud Map information for the virtual node.

attributes -> (list)

A string map that contains attributes with values that you can use to filter instances by any custom attribute that you specified when you registered the instance. Only instances that match all of the specified key/value pairs will be returned.

(structure)

An object representing the AWS Cloud Map attribute information for your virtual node.

key -> (string)

The name of an AWS Cloud Map service instance attribute key. Any AWS Cloud Map service instance that contains the specified key and value is returned.

value -> (string)

The value of an AWS Cloud Map service instance attribute key. Any AWS Cloud Map service instance that contains the specified key and value is returned.

namespaceName -> (string)

The name of the AWS Cloud Map namespace to use.

serviceName -> (string)

The name of the AWS Cloud Map service to use.

dns -> (structure)

Specifies the DNS information for the virtual node.

hostname -> (string)

Specifies the DNS service discovery hostname for the virtual node.

status -> (structure)

The current status for the virtual node.

status -> (string)

The current status of the virtual node.

virtualNodeName -> (string)

The name of the virtual node.