agent: clarified a number of comments per PR feedback

agent/agent_endpoint_test.go

@@ -1372,6 +1372,9 @@ func TestAgent_RegisterService_ConnectProxy(t *testing.T) {
 	a := NewTestAgent(t.Name(), "")
 	defer a.Shutdown()
 
+	// Register a proxy. Note that the destination doesn't exist here on
+	// this agent or in the catalog at all. This is intended and part
+	// of the design.
 	args := &structs.ServiceDefinition{
 		Kind:             structs.ServiceKindConnectProxy,
 		Name:             "connect-proxy",
@@ -1388,7 +1391,7 @@ func TestAgent_RegisterService_ConnectProxy(t *testing.T) {
 	assert.Nil(err)
 	assert.Nil(obj)
 
-	// Ensure the servie
+	// Ensure the service
 	svc, ok := a.State.Services()["connect-proxy"]
 	assert.True(ok, "has service")
 	assert.Equal(structs.ServiceKindConnectProxy, svc.Kind)

agent/consul/catalog_endpoint_test.go

@@ -393,7 +393,6 @@ func TestCatalog_Register_ConnectProxy_ACLProxyDestination(t *testing.T) {
 		c.ACLDatacenter = "dc1"
 		c.ACLMasterToken = "root"
 		c.ACLDefaultPolicy = "deny"
-		c.ACLEnforceVersion8 = false
 	})
 	defer os.RemoveAll(dir1)
 	defer s1.Shutdown()
@@ -1802,7 +1801,6 @@ func TestCatalog_ListServiceNodes_ConnectProxy_ACL(t *testing.T) {
 		c.ACLDatacenter = "dc1"
 		c.ACLMasterToken = "root"
 		c.ACLDefaultPolicy = "deny"
-		c.ACLEnforceVersion8 = false
 	})
 	defer os.RemoveAll(dir1)
 	defer s1.Shutdown()

agent/dns_test.go

@@ -1049,7 +1049,7 @@ func TestDNS_ConnectServiceLookup(t *testing.T) {
 	a := NewTestAgent(t.Name(), "")
 	defer a.Shutdown()
 
-	// Register a node with an external service.
+	// Register
 	{
 		args := structs.TestRegisterRequestProxy(t)
 		args.Service.ProxyDestination = "db"

agent/structs/service_definition.go

@@ -1,6 +1,7 @@
 package structs
 
-// ServiceDefinition is used to JSON decode the Service definitions
+// ServiceDefinition is used to JSON decode the Service definitions. For
+// documentation on specific fields see NodeService which is better documented.
 type ServiceDefinition struct {
 	Kind              ServiceKind
 	ID                string

agent/structs/structs.go

@@ -491,6 +491,9 @@ type NodeService struct {
 
 	// ProxyDestination is the name of the service that this service is
 	// a Connect proxy for. This is only valid if Kind is "connect-proxy".
+	// The destination may be a service that isn't present in the catalog.
+	// This is expected and allowed to allow for proxies to come up
+	// earlier than their target services.
 	ProxyDestination string
 
 	RaftIndex