WIP

config/resources/access-token.yaml

@@ -7,8 +7,8 @@ description: |
   A short-lived credential used to create a link.  An access token
   contains the URL and secret code of a corresponding access grant.
 
-  Access tokens are often [issued][issue] and [redeemed][redeem] using
-  the Skupper CLI.
+  **Note:** Access tokens are often [issued][issue] and
+  [redeemed][redeem] using the Skupper CLI.
 
   [issue]: {{site_prefix}}/commands/token/issue.html
   [redeem]: {{site_prefix}}/commands/token/redeem.html

config/resources/connector.yaml

@@ -6,12 +6,12 @@ description: |
   remote [sites](site.html).  Listeners and connectors are matched by
   routing key.
 
-  On Kubernetes, a connector has a selector and port for specifying
-  workload pods.
+  On Kubernetes, a Connector resource has a selector and port for
+  specifying workload pods.
 
-  On Docker, Podman, and Linux, a connector has a host and port for
-  specifying a local server.  Optionally, Kubernetes can also use a
-  host and port.
+  On Docker, Podman, and Linux, a Connector resource has a host and
+  port for specifying a local server.  Optionally, Kubernetes can also
+  use a host and port.
 examples:
   - description: |
       A connector in site East for the Hello World backend service

config/resources/link.yaml

@@ -6,8 +6,10 @@ description: |
   Links carry application connections and requests.  A set of linked
   sites constitutes a network.
 
-  To create a link to a remote site, the remote site must enable
-  _link access_.  Link access provides an external access point for
+  A Link resource has remote connection endpoints and TLS credentials
+  for establishing a mutual TLS connection to a remote site.  To
+  create an active link, the remote site must first enable _link
+  access_.  Link access provides an external access point for
   accepting links.
 
   **Note:** Links are not usually created directly.  Instead, you can

config/resources/listener.yaml

@@ -6,9 +6,9 @@ description: |
   [connectors](connector.html) in remote [sites](site.html).
   Listeners and connectors are matched by routing key.
 
-  A listener has a host and port for accepting connections from local
-  clients.  To expose a multi-port service, create multiple listeners
-  with the same host value.
+  A Listener resource has a host and port for accepting connections
+  from local clients.  To expose a multi-port service, create multiple
+  listeners with the same host value.
 examples:
   - description: |
       A listener in site West for the Hello World backend service

config/resources/site.yaml

@@ -1,19 +1,13 @@
 name: Site
 related_concepts: [network, platform]
+related_resources: [Link]
 description: |
   A site is a place on the network where application workloads are
   running.  Sites are joined by [links](link.html).
 
-  There can be only one active Site resource per namespace.
-
-  On Kubernetes, a Site input resource results in the following output
-  resources:
-
-    - A Deployment and ConfigMap for the router
-    - A ServiceAccount, Role, and RoleBinding (if `serviceAccount` is
-      not set)
-    - A Secret containing a signing CA for site linking (if
-      `defaultIssuer` is not set)
+  The Site resource is the basis for site configuration.  It is the
+  parent of all Skupper resources in its namespace.  There can be only
+  one active Site resource per namespace.
 examples:
   - description: A minimal site
     yaml: |

input/resources/access-token.md

@@ -19,8 +19,8 @@ refdog_object_has_attributes: true
 A short-lived credential used to create a link.  An access token
 contains the URL and secret code of a corresponding access grant.
 
-Access tokens are often [issued][issue] and [redeemed][redeem] using
-the Skupper CLI.
+**Note:** Access tokens are often [issued][issue] and
+[redeemed][redeem] using the Skupper CLI.
 
 [issue]: {{site_prefix}}/commands/token/issue.html
 [redeem]: {{site_prefix}}/commands/token/redeem.html

input/resources/connector.md

@@ -18,12 +18,12 @@ A connector binds a local workload to [listeners](listener.html) in
 remote [sites](site.html).  Listeners and connectors are matched by
 routing key.
 
-On Kubernetes, a connector has a selector and port for specifying
-workload pods.
+On Kubernetes, a Connector resource has a selector and port for
+specifying workload pods.
 
-On Docker, Podman, and Linux, a connector has a host and port for
-specifying a local server.  Optionally, Kubernetes can also use a
-host and port.
+On Docker, Podman, and Linux, a Connector resource has a host and
+port for specifying a local server.  Optionally, Kubernetes can also
+use a host and port.
 
 ~~~ yaml
 apiVersion: skupper.io/v2alpha1

input/resources/link.md

@@ -18,8 +18,10 @@ A link is a channel for communication between [sites](site.html).
 Links carry application connections and requests.  A set of linked
 sites constitutes a network.
 
-To create a link to a remote site, the remote site must enable
-_link access_.  Link access provides an external access point for
+A Link resource has remote connection endpoints and TLS credentials
+for establishing a mutual TLS connection to a remote site.  To
+create an active link, the remote site must first enable _link
+access_.  Link access provides an external access point for
 accepting links.
 
 **Note:** Links are not usually created directly.  Instead, you can

input/resources/listener.md

@@ -18,9 +18,9 @@ A listener binds a local connection endpoint to
 [connectors](connector.html) in remote [sites](site.html).
 Listeners and connectors are matched by routing key.
 
-A listener has a host and port for accepting connections from local
-clients.  To expose a multi-port service, create multiple listeners
-with the same host value.
+A Listener resource has a host and port for accepting connections
+from local clients.  To expose a multi-port service, create multiple
+listeners with the same host value.
 
 ~~~ yaml
 apiVersion: skupper.io/v2alpha1

input/resources/overview.md

@@ -27,6 +27,15 @@ input and produces platform-specific resources as output.  The output
 resources configure the local site and router for the desired
 connectivity.
 
+On Kubernetes, a Site input resource results in the following output
+resources:
+
+- A Deployment and ConfigMap for the router
+- A ServiceAccount, Role, and RoleBinding (if `serviceAccount` is
+  not set)
+- A Secret containing a signing CA for site linking (if
+  `defaultIssuer` is not set)
+
 #### Operations
 
 Creation, updates, deletion

input/resources/site.md

@@ -9,6 +9,8 @@ refdog_links:
   url: /concepts/network.html
 - title: Platform concept
   url: /concepts/platform.html
+- title: Link resource
+  url: /resources/link.html
 refdog_object_has_attributes: true
 ---
 
@@ -17,16 +19,9 @@ refdog_object_has_attributes: true
 A site is a place on the network where application workloads are
 running.  Sites are joined by [links](link.html).
 
-There can be only one active Site resource per namespace.
-
-On Kubernetes, a Site input resource results in the following output
-resources:
-
-  - A Deployment and ConfigMap for the router
-  - A ServiceAccount, Role, and RoleBinding (if `serviceAccount` is
-    not set)
-  - A Secret containing a signing CA for site linking (if
-    `defaultIssuer` is not set)
+The Site resource is the basis for site configuration.  It is the
+parent of all Skupper resources in its namespace.  There can be only
+one active Site resource per namespace.
 
 ~~~ yaml
 apiVersion: skupper.io/v2alpha1