Merge pull request #8 from hashicorp/update-readme-cli-example

Update README to have full, correct examples

README.md

@@ -26,6 +26,62 @@ given credentials will be used to create a new credential, and then the given
 credential will be revoked. In this way, after rotation, only Boundary knows the
 client secret in use by this plugin.
 
+## Getting Started
+
+Refer to [Attributes and Secrets](#attributes-and-secrets) for more detail on
+configuration options for host catalogs and sets.
+
+To create a host catalog (using default scope created by `boundary dev`):
+
+```
+boundary host-catalogs create plugin \
+ -scope-id p_1234567890 \
+ -name "Example Plugin-Based Host Catalog" \
+ -description "Description for plugin-based host catalog" \
+ -plugin-name aws \
+ -attr region=REGION \
+ -secret access_key_id='KEY' \
+ -secret secret_access_key='SECRET'
+```
+
+To create a host set, filtering the host set based on tag keys `foo` or `bar`
+(either tag can be present), ensuring that any targets set to this host set only
+connect to external addresses in the `54.0.0.0/8` class A subnet:
+
+```
+boundary host-sets create plugin \
+ -host-catalog-id HOST_CATALOG_ID \
+ -name "Example Plugin-Based Host Set" \
+ -description "Description for plugin-based host set" \
+ -attr filters=tag-key=foo,bar \
+ -preferred-endpoint "cidr:54.0.0.0/8"
+```
+
+As above, but instances must have both tags (both `foo` and `bar` *must* be
+present):
+
+```
+boundary host-sets create plugin \
+ -host-catalog-id HOST_CATALOG_ID \
+ -name "Example Plugin-Based Host Set" \
+ -description "Description for plugin-based host set" \
+ -attr filters=tag-key=foo \
+ -attr filters=tag-key=bar \
+ -preferred-endpoint "cidr:54.0.0.0/8"
+```
+
+As above, but matching on tag key and launch date:
+
+```
+boundary host-sets create plugin \
+ -host-catalog-id HOST_CATALOG_ID \
+ -name "Example Plugin-Based Host Set" \
+ -description "Description for plugin-based host set" \
+ -attr filters=tag-key=foo \
+ -attr filters=launch-time=2022-01-04T* \
+ -preferred-endpoint "cidr:54.0.0.0/8"
+```
+
 ## Required IAM Privileges
 
 The following IAM privileges, at the very least, are required to be attached to
@@ -97,13 +153,3 @@ The following attributes are valid on an AWS host Set resource:
   a comma-separated list. For a list of filter options, check out
   [describe-instances in the AWS CLI
   reference](https://docs.aws.amazon.com/cli/latest/reference/ec2/describe-instances.html).
-
-#### Supplying Filters on the Boundary CLI
-
-As `filters` is part of a host set's attributes and may contain dashes which are
-not identifier-friendly, it's recommended you that supply attributes for AWS
-host sets as a full JSON string. Example:
-
-```
-boundary host-sets create plugin -host-catalog-id hc_1234567890 --attributes '{"filters":{"tag-name":["foo"]}}'
-```

plugin/plugin.go

@@ -543,16 +543,22 @@ func awsInstanceToHost(instance *ec2.Instance) (*pb.ListHostsResponseHost, error
 	// External ID is the instance ID.
 	result.ExternalId = aws.StringValue(instance.InstanceId)
 
-	// First IP address is always the private IP address field if it's
-	// populated
+	// First IP address/dns name are always the private fields if they
+	// are populated
 	if aws.StringValue(instance.PrivateIpAddress) != "" {
 		result.IpAddresses = append(result.IpAddresses, aws.StringValue(instance.PrivateIpAddress))
 	}
+	if aws.StringValue(instance.PrivateDnsName) != "" {
+		result.DnsNames = append(result.DnsNames, aws.StringValue(instance.PrivateDnsName))
+	}
 
-	// Public IP address is next.
+	// Public IP address/dns names are next
 	if aws.StringValue(instance.PublicIpAddress) != "" {
 		result.IpAddresses = append(result.IpAddresses, aws.StringValue(instance.PublicIpAddress))
 	}
+	if aws.StringValue(instance.PublicDnsName) != "" {
+		result.DnsNames = append(result.DnsNames, aws.StringValue(instance.PublicDnsName))
+	}
 
 	// Now go through all of the interfaces and log the IP address of
 	// every interface.
@@ -562,6 +568,15 @@ func awsInstanceToHost(instance *ec2.Instance) (*pb.ListHostsResponseHost, error
 			return nil, errors.New("response integrity error: interface entry is nil")
 		}
 
+		// Populate default IP addresses/DNS name similar to how we do
+		// for the entire instance.
+		if aws.StringValue(iface.PrivateIpAddress) != "" && !stringInSlice(result.IpAddresses, aws.StringValue(iface.PrivateIpAddress)) {
+			result.IpAddresses = append(result.IpAddresses, aws.StringValue(iface.PrivateIpAddress))
+		}
+		if aws.StringValue(iface.PrivateDnsName) != "" && !stringInSlice(result.DnsNames, aws.StringValue(iface.PrivateDnsName)) {
+			result.DnsNames = append(result.DnsNames, aws.StringValue(iface.PrivateDnsName))
+		}
+
 		// Iterate through the private IP addresses and log the
 		// information.
 		for _, addr := range iface.PrivateIpAddresses {
@@ -569,21 +584,20 @@ func awsInstanceToHost(instance *ec2.Instance) (*pb.ListHostsResponseHost, error
 				return nil, errors.New("response integrity error: interface address entry is nil")
 			}
 
-			// Check to see if the PrivateIpAddress matches the one
-			// reported at the top-level of the instance (let's call it the
-			// "default address"). If it doesn't, add it.
-			if aws.StringValue(addr.PrivateIpAddress) != "" {
-				if aws.StringValue(instance.PrivateIpAddress) != aws.StringValue(addr.PrivateIpAddress) {
-					result.IpAddresses = append(result.IpAddresses, aws.StringValue(addr.PrivateIpAddress))
-				}
+			// Add private address/dns name if they have not been added yet
+			if aws.StringValue(addr.PrivateIpAddress) != "" && !stringInSlice(result.IpAddresses, aws.StringValue(addr.PrivateIpAddress)) {
+				result.IpAddresses = append(result.IpAddresses, aws.StringValue(addr.PrivateIpAddress))
+			}
+			if aws.StringValue(addr.PrivateDnsName) != "" && !stringInSlice(result.DnsNames, aws.StringValue(addr.PrivateDnsName)) {
+				result.DnsNames = append(result.DnsNames, aws.StringValue(addr.PrivateDnsName))
 			}
 
-			// Do the same for the default public IP address and the
-			// public association on the interface.
-			if addr.Association != nil && addr.Association.PublicIp != nil && aws.StringValue(addr.Association.PublicIp) != "" {
-				if instance.PublicIpAddress != nil && aws.StringValue(instance.PublicIpAddress) != aws.StringValue(addr.Association.PublicIp) {
-					result.IpAddresses = append(result.IpAddresses, aws.StringValue(addr.Association.PublicIp))
-				}
+			// Add public address/dns name if they have not been added yet
+			if addr.Association != nil && aws.StringValue(addr.Association.PublicIp) != "" && !stringInSlice(result.IpAddresses, aws.StringValue(addr.Association.PublicIp)) {
+				result.IpAddresses = append(result.IpAddresses, aws.StringValue(addr.Association.PublicIp))
+			}
+			if addr.Association != nil && aws.StringValue(addr.Association.PublicDnsName) != "" && !stringInSlice(result.DnsNames, aws.StringValue(addr.Association.PublicDnsName)) {
+				result.DnsNames = append(result.DnsNames, aws.StringValue(addr.Association.PublicDnsName))
 			}
 		}
 
@@ -602,3 +616,13 @@ func awsInstanceToHost(instance *ec2.Instance) (*pb.ListHostsResponseHost, error
 	// Done
 	return result, nil
 }
+
+func stringInSlice(s []string, x string) bool {
+	for _, y := range s {
+		if x == y {
+			return true
+		}
+	}
+
+	return false
+}

plugin/plugin_test.go

@@ -1380,15 +1380,21 @@ func TestAwsInstanceToHost(t *testing.T) {
 			instance: &ec2.Instance{
 				InstanceId:       aws.String("foobar"),
 				PrivateIpAddress: aws.String("10.0.0.1"),
+				PrivateDnsName:   aws.String("test.example.internal"),
 				PublicIpAddress:  aws.String("1.1.1.1"),
+				PublicDnsName:    aws.String("test.example.com"),
 				NetworkInterfaces: []*ec2.InstanceNetworkInterface{
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.1"),
+						PrivateDnsName:   aws.String("test.example.internal"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								Association: &ec2.InstanceNetworkInterfaceAssociation{
-									PublicIp: aws.String("1.1.1.1"),
+									PublicIp:      aws.String("1.1.1.1"),
+									PublicDnsName: aws.String("test.example.com"),
 								},
 								PrivateIpAddress: aws.String("10.0.0.1"),
+								PrivateDnsName:   aws.String("test.example.internal"),
 							},
 						},
 					},
@@ -1397,6 +1403,7 @@ func TestAwsInstanceToHost(t *testing.T) {
 			expected: &pb.ListHostsResponseHost{
 				ExternalId:  "foobar",
 				IpAddresses: []string{"10.0.0.1", "1.1.1.1"},
+				DnsNames:    []string{"test.example.internal", "test.example.com"},
 			},
 		},
 		{
@@ -1404,11 +1411,15 @@ func TestAwsInstanceToHost(t *testing.T) {
 			instance: &ec2.Instance{
 				InstanceId:       aws.String("foobar"),
 				PrivateIpAddress: aws.String("10.0.0.1"),
+				PrivateDnsName:   aws.String("test.example.internal"),
 				NetworkInterfaces: []*ec2.InstanceNetworkInterface{
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.1"),
+						PrivateDnsName:   aws.String("test.example.internal"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								PrivateIpAddress: aws.String("10.0.0.1"),
+								PrivateDnsName:   aws.String("test.example.internal"),
 							},
 						},
 					},
@@ -1417,6 +1428,7 @@ func TestAwsInstanceToHost(t *testing.T) {
 			expected: &pb.ListHostsResponseHost{
 				ExternalId:  "foobar",
 				IpAddresses: []string{"10.0.0.1"},
+				DnsNames:    []string{"test.example.internal"},
 			},
 		},
 		{
@@ -1424,22 +1436,31 @@ func TestAwsInstanceToHost(t *testing.T) {
 			instance: &ec2.Instance{
 				InstanceId:       aws.String("foobar"),
 				PrivateIpAddress: aws.String("10.0.0.1"),
+				PrivateDnsName:   aws.String("test.example.internal"),
 				PublicIpAddress:  aws.String("1.1.1.1"),
+				PublicDnsName:    aws.String("test.example.com"),
 				NetworkInterfaces: []*ec2.InstanceNetworkInterface{
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.2"),
+						PrivateDnsName:   aws.String("test2.example.internal"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								PrivateIpAddress: aws.String("10.0.0.2"),
+								PrivateDnsName:   aws.String("test2.example.internal"),
 							},
 						},
 					},
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.1"),
+						PrivateDnsName:   aws.String("test.example.internal"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								Association: &ec2.InstanceNetworkInterfaceAssociation{
-									PublicIp: aws.String("1.1.1.1"),
+									PublicIp:      aws.String("1.1.1.1"),
+									PublicDnsName: aws.String("test.example.com"),
 								},
 								PrivateIpAddress: aws.String("10.0.0.1"),
+								PrivateDnsName:   aws.String("test.example.internal"),
 							},
 						},
 					},
@@ -1448,6 +1469,7 @@ func TestAwsInstanceToHost(t *testing.T) {
 			expected: &pb.ListHostsResponseHost{
 				ExternalId:  "foobar",
 				IpAddresses: []string{"10.0.0.1", "1.1.1.1", "10.0.0.2"},
+				DnsNames:    []string{"test.example.internal", "test.example.com", "test2.example.internal"},
 			},
 		},
 		{
@@ -1455,25 +1477,35 @@ func TestAwsInstanceToHost(t *testing.T) {
 			instance: &ec2.Instance{
 				InstanceId:       aws.String("foobar"),
 				PrivateIpAddress: aws.String("10.0.0.1"),
+				PrivateDnsName:   aws.String("test.example.internal"),
 				PublicIpAddress:  aws.String("1.1.1.1"),
+				PublicDnsName:    aws.String("test.example.com"),
 				NetworkInterfaces: []*ec2.InstanceNetworkInterface{
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.2"),
+						PrivateDnsName:   aws.String("test2.example.internal"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								Association: &ec2.InstanceNetworkInterfaceAssociation{
-									PublicIp: aws.String("1.1.1.2"),
+									PublicIp:      aws.String("1.1.1.2"),
+									PublicDnsName: aws.String("test2.example.com"),
 								},
 								PrivateIpAddress: aws.String("10.0.0.2"),
+								PrivateDnsName:   aws.String("test2.example.internal"),
 							},
 						},
 					},
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.1"),
+						PrivateDnsName:   aws.String("test.example.internal"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								Association: &ec2.InstanceNetworkInterfaceAssociation{
-									PublicIp: aws.String("1.1.1.1"),
+									PublicIp:      aws.String("1.1.1.1"),
+									PublicDnsName: aws.String("test.example.com"),
 								},
 								PrivateIpAddress: aws.String("10.0.0.1"),
+								PrivateDnsName:   aws.String("test.example.internal"),
 							},
 						},
 					},
@@ -1482,6 +1514,7 @@ func TestAwsInstanceToHost(t *testing.T) {
 			expected: &pb.ListHostsResponseHost{
 				ExternalId:  "foobar",
 				IpAddresses: []string{"10.0.0.1", "1.1.1.1", "10.0.0.2", "1.1.1.2"},
+				DnsNames:    []string{"test.example.internal", "test.example.com", "test2.example.internal", "test2.example.com"},
 			},
 		},
 		{
@@ -1489,18 +1522,25 @@ func TestAwsInstanceToHost(t *testing.T) {
 			instance: &ec2.Instance{
 				InstanceId:       aws.String("foobar"),
 				PrivateIpAddress: aws.String("10.0.0.1"),
+				PrivateDnsName:   aws.String("test.example.internal"),
 				PublicIpAddress:  aws.String("1.1.1.1"),
+				PublicDnsName:    aws.String("test.example.com"),
 				NetworkInterfaces: []*ec2.InstanceNetworkInterface{
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.1"),
+						PrivateDnsName:   aws.String("test.example.internal"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								Association: &ec2.InstanceNetworkInterfaceAssociation{
-									PublicIp: aws.String("1.1.1.1"),
+									PublicIp:      aws.String("1.1.1.1"),
+									PublicDnsName: aws.String("test.example.com"),
 								},
 								PrivateIpAddress: aws.String("10.0.0.1"),
+								PrivateDnsName:   aws.String("test.example.internal"),
 							},
 							&ec2.InstancePrivateIpAddress{
 								PrivateIpAddress: aws.String("10.0.0.2"),
+								PrivateDnsName:   aws.String("test2.example.internal"),
 							},
 						},
 					},
@@ -1509,6 +1549,7 @@ func TestAwsInstanceToHost(t *testing.T) {
 			expected: &pb.ListHostsResponseHost{
 				ExternalId:  "foobar",
 				IpAddresses: []string{"10.0.0.1", "1.1.1.1", "10.0.0.2"},
+				DnsNames:    []string{"test.example.internal", "test.example.com", "test2.example.internal"},
 			},
 		},
 		{
@@ -1516,9 +1557,12 @@ func TestAwsInstanceToHost(t *testing.T) {
 			instance: &ec2.Instance{
 				InstanceId:       aws.String("foobar"),
 				PrivateIpAddress: aws.String("10.0.0.1"),
+				PrivateDnsName:   aws.String("test.example.internal"),
 				PublicIpAddress:  aws.String("1.1.1.1"),
+				PublicDnsName:    aws.String("test.example.com"),
 				NetworkInterfaces: []*ec2.InstanceNetworkInterface{
 					&ec2.InstanceNetworkInterface{
+						PrivateIpAddress: aws.String("10.0.0.1"),
 						PrivateIpAddresses: []*ec2.InstancePrivateIpAddress{
 							&ec2.InstancePrivateIpAddress{
 								Association: &ec2.InstanceNetworkInterfaceAssociation{
@@ -1537,6 +1581,7 @@ func TestAwsInstanceToHost(t *testing.T) {
 			expected: &pb.ListHostsResponseHost{
 				ExternalId:  "foobar",
 				IpAddresses: []string{"10.0.0.1", "1.1.1.1", "some::fake::address"},
+				DnsNames:    []string{"test.example.internal", "test.example.com"},
 			},
 		},
 	}