diff --git a/.plano.py b/.plano.py index 5d897b19..574ba7bc 100644 --- a/.plano.py +++ b/.plano.py @@ -45,4 +45,4 @@ def update_crds(): assert is_dir(extracted_dir) with working_dir(extracted_dir): - copy("api/types/crds", crd_dir, inside=False) + copy("config/crd/bases", crd_dir, inside=False) diff --git a/config/resources/access-grant.yaml b/config/resources/access-grant.yaml index 8dd1afbb..473c4fef 100644 --- a/config/resources/access-grant.yaml +++ b/config/resources/access-grant.yaml @@ -3,77 +3,79 @@ related_concepts: [access-token] related_resources: [access-token] related_commands: [token/issue] links: [skupper/site-linking] -description: | - Permission to redeem access tokens for links to the local - site. A remote site can use a token containing the grant - URL and secret code to obtain a certificate signed by the - grant's certificate authority (CA), within a certain - expiration window and for a limited number of redemptions. +description: |- + Permission to redeem access tokens for links to the local site. + A remote site can use a token containing the grant URL and secret + code to obtain a certificate signed by the grant's certificate authority (CA), + within a certain expiration window and for a limited number of redemptions. - The `code`, `url`, and `ca` properties of the resource - status are used to generate access tokens from the grant. + The code, url, and ca properties of the resource status are used to generate access tokens from the grant. metadata: include_properties: [metadata/*] spec: include_properties: [settings] properties: - name: redemptionsAllowed - description: | - The number of times an access token for this grant can - be redeemed. + description: |- + The maximum number of times an access token for this grant can be redeemed. + The default value is `1`. default: 1 - name: expirationWindow - description: | - The period of time in which an access token for this - grant can be redeemed. + description: |- + The period of time in which an access token for this grant can be redeemed. + The default value is `15m`. default: 15m - name: code group: advanced - description: | - The secret code to use to authenticate access tokens submitted - for redemption. - - If not set, a value is generated and placed in the `code` - status property. + description: |- + Advanced. The secret code to use to authenticate access tokens submitted for redemption. + If not set, a value is generated and placed in the code status property. - name: issuer group: advanced platforms: [Kubernetes] links: [skupper/router-tls, kubernetes/tls-secrets] - description: | - The name of a Kubernetes secret used to generate a - certificate when redeeming a token for this grant. + description: |- + Advanced. The name of a Kubernetes secret used to generate a certificate when redeeming a token for this grant. + If not set, `defaultIssuer` on the Site resource is used. + description: |- + Permission to redeem access tokens for links to the local site. + A remote site can use a token containing the grant URL and secret + code to obtain a certificate signed by the grant's certificate authority (CA), + within a certain expiration window and for a limited number of redemptions. - If not set, `defaultIssuer` on the Site rsource is used. + The code, url, and ca properties of the resource status are used to generate access tokens from the grant. status: include_properties: [status/*] properties: - name: status + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. - name: message + description: |- + A human-readable status message. Error messages are reported here. - name: redemptions - description: | - The number of times a token for this grant has been - redeemed. + description: |- + The number of times a token for this grant has been redeemed. - name: expirationTime - description: | + description: |- The point in time when the grant expires. - name: url - description: | + description: |- The URL of the token-redemption service for this grant. - name: ca - description: | - The trusted server certificate of the token-redemption - service for this grant. + description: |- + The trusted server certificate of the token-redemption service for this grant. - name: code - description: | - The secret code used to authenticate access tokens - submitted for redemption. + description: |- + The secret code used to authenticate access tokens submitted for redemption. default: _Generated_ - name: conditions - description: | - @description@ + description: |- + A set of named conditions describing the current state of the resource. - `Processed`: The controller has accepted the grant. - - `Resolved`: The grant service is available to process tokens - for this grant. - - `Ready`: The grant is ready to use. All other - conditions are true. + - `Resolved`: The grant service is available to process tokens for this grant. + - `Ready`: The grant is ready to use. All other conditions are true. diff --git a/config/resources/access-token.yaml b/config/resources/access-token.yaml index 60d3c6f6..d0ed30e7 100644 --- a/config/resources/access-token.yaml +++ b/config/resources/access-token.yaml @@ -3,46 +3,42 @@ related_concepts: [access-token] related_resources: [access-grant] related_commands: [token/issue, token/redeem] links: [skupper/site-linking] -description: | - A short-lived credential used to create a link. An access token - contains the URL and secret code of a corresponding access grant. - - **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 +description: |- + A short-lived credential used to create a link between sites. + An access token contains the URL and secret code of a corresponding access grant. + **Note:** Access tokens are typically issued and redeemed using the Skupper CLI. metadata: include_properties: [metadata/*] spec: include_properties: [settings] properties: - name: url - description: | + description: |- The URL of the grant service at the remote site. - name: ca required: false - description: | - The trusted server certificate of the grant service at the - remote site. + description: |- + The trusted server certificate of the grant service at the remote site. - name: code - description: | - The secret code used to authenticate the token when - submitted for redemption. + description: |- + The secret code used to authenticate the token when submitted for redemption. - name: linkCost default: 1 links: [skupper/load-balancing] - description: | + description: |- The link cost to use when creating the link. + description: |- + A short-lived credential used to create a link between sites. + An access token contains the URL and secret code of a corresponding access grant. + **Note:** Access tokens are typically issued and redeemed using the Skupper CLI. status: include_properties: [status/*] properties: - name: redeemed - description: | - True if the token has been redeemed. Once a token is - redeemed, it cannot be used again. + description: |- + True if the token has been redeemed. Once a token is redeemed, it cannot be used again. - name: conditions - description: | - @description@ + description: |- + A set of named conditions describing the current state of the resource. - `Redeemed`: The token has been exchanged for a link. diff --git a/config/resources/attached-connector-binding.yaml b/config/resources/attached-connector-binding.yaml index 6beef66d..c6d297fe 100644 --- a/config/resources/attached-connector-binding.yaml +++ b/config/resources/attached-connector-binding.yaml @@ -2,8 +2,11 @@ name: AttachedConnectorBinding platforms: [Kubernetes] related_resources: [attached-connector] links: [skupper/attached-connectors] -description: | - A binding to an attached connector in a peer namespace. +description: |- + An attached connector binding is a binding to an attached connector in a peer namespace that allows you to + bring a workload into your existing VAN without creating a separate site or establishing inter-site links. + The name of this resource must be the same as that of the associated AttachedConnector resource in the peer + namespace. metadata: include_properties: [metadata/*] properties: @@ -13,13 +16,18 @@ metadata: The name must be the same as that of the associated AttachedConnector resource in the connector namespace. + description: |- + An attached connector binding is a binding to an attached connector in a peer namespace that allows you to + bring a workload into your existing VAN without creating a separate site or establishing inter-site links. + The name of this resource must be the same as that of the associated AttachedConnector resource in the peer + namespace. spec: - include_properties: [connector/spec/routingKey, connector/spec/exposePodsByName, settings] + include_properties: [connector/spec/routingKey, + connector/spec/exposePodsByName, settings] properties: - name: connectorNamespace - description: | - The name of the namespace where the associated - AttachedConnector is located. + description: |- + The name of the namespace where the associated AttachedConnector is located. status: include_properties: [status/*, connector/status/hasMatchingListener] exclude_properties: [status/message] diff --git a/config/resources/attached-connector.yaml b/config/resources/attached-connector.yaml index cffbfbd2..50af2dd9 100644 --- a/config/resources/attached-connector.yaml +++ b/config/resources/attached-connector.yaml @@ -2,8 +2,9 @@ name: AttachedConnector platforms: [Kubernetes] related_resources: [attached-connector-binding] links: [skupper/attached-connectors] -description: | - A connector in a peer namespace. +description: |- + An attached connector is a connector in a peer namespace that allows you to bring a workload into your existing VAN without creating a separate site or establishing inter-site links. + The name of this resource must be the same as that of the associated AttachedConnectorBinding resource in the site namespace. metadata: include_properties: [metadata/*] properties: @@ -13,6 +14,9 @@ metadata: The name must be the same as that of the associated AttachedConnectorBinding resource in the site namespace. + description: |- + An attached connector is a connector in a peer namespace that allows you to bring a workload into your existing VAN without creating a separate site or establishing inter-site links. + The name of this resource must be the same as that of the associated AttachedConnectorBinding resource in the site namespace. spec: include_properties: [connector/spec/*, settings] exclude_properties: @@ -23,9 +27,8 @@ spec: - connector/spec/verifyHostname properties: - name: siteNamespace - description: | - The name of the namespace in which the site this connector - should be attached to is defined. + description: |- + The name of the namespace in which the site this connector should be attached to is defined. status: include_properties: [status/*, connector/status/selectedPods] exclude_properties: [status/message] diff --git a/config/resources/connector.yaml b/config/resources/connector.yaml index 0ccd6e4c..dad93b1b 100644 --- a/config/resources/connector.yaml +++ b/config/resources/connector.yaml @@ -1,17 +1,15 @@ name: Connector related_resources: [listener] links: [skupper/service-exposure] -description: | - A connector binds a local workload to [listeners](listener.html) in - remote [sites](site.html). Listeners and connectors are matched by - routing key. +description: |- + A connector binds a local workload to listeners in remote sites. Listeners + and connectors are matched by routing key. - On Kubernetes, a Connector resource 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 resource 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 @@ -29,5 +27,67 @@ metadata: include_properties: [metadata/*] spec: include_properties: [connector/spec/*, settings] + properties: + - name: routingKey + description: |- + The identifier used to route traffic from listeners to connectors. + To expose a local workload to a remote site, the remote listener and + the local connector must have matching routing keys. + # will be filled from CRD + - name: selector + description: |- + A Kubernetes label selector for specifying target server pods. It uses + = syntax. + + On Kubernetes, either selector or host is required. + - name: host + description: |- + The hostname or IP address of the server. This is an alternative to + selector for specifying the target server. + + On Kubernetes, either selector or host is required. + + On Docker, Podman, or Linux, host is required. + - name: port + description: |- + The port on the target server to connect to. + - name: tlsCredentials + description: |- + The name of a bundle of TLS certificates used for secure router-to-server + communication. The bundle contains the trusted server certificate + (usually a CA). It optionally includes a client certificate and key for + mutual TLS. + + On Kubernetes, the value is the name of a Secret in the current namespace. + On Docker, Podman, and Linux, the value is the name of a directory under + input/certs/ in the current namespace. + - name: useClientCert + description: |- + Send the client certificate when connecting in order to enable mutual TLS. + - name: verifyHostname + description: |- + If true, require that the hostname of the server connected to matches the + hostname in the server's certificate. + - name: includeNotReadyPods + description: |- + If true, include server pods in the NotReady state. + - name: exposePodsByName + description: |- + If true, expose each pod as an individual service. + - name: settings + description: |- + A map containing additional settings. Each map entry has a string name and a + string value. + + Note: In general, we recommend not changing settings from their default values. + description: |- + A connector binds a local workload to listeners in remote sites. Listeners + and connectors are matched by routing key. + + On Kubernetes, a Connector resource has a selector and port for specifying + workload pods. + + 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. status: include_properties: [status/*, connector/status/*] diff --git a/config/resources/link.yaml b/config/resources/link.yaml index 58581817..5cad3335 100644 --- a/config/resources/link.yaml +++ b/config/resources/link.yaml @@ -1,8 +1,8 @@ name: Link related_resources: [access-token] links: [skupper/site-linking] -description: | - A link is a channel for communication between [sites](site.html). +description: |- + A link is a channel for communication between sites. Links carry application connections and requests. A set of linked sites constitutes a network. @@ -13,9 +13,7 @@ description: | accepting links. **Note:** Links are not usually created directly. Instead, you can - use an [access token][token] to obtain a link. - - [token]: access-token.html + use an AccessToken to obtain a link. metadata: include_properties: [metadata/*] spec: @@ -24,16 +22,16 @@ spec: - name: cost default: 1 links: [skupper/load-balancing] - description: | - The configured routing cost of sending traffic over - the link. + description: |- + The configured routing cost of sending traffic over the link. - name: endpoints - description: | + description: |- An array of connection endpoints. Each item has a name, host, port, and group. - name: tlsCredentials - links: [skupper/router-tls, kubernetes/tls-secrets, skupper/system-tls-credentials] - description: | + links: [skupper/router-tls, kubernetes/tls-secrets, + skupper/system-tls-credentials] + description: |- The name of a bundle of certificates used for mutual TLS router-to-router communication. The bundle contains the client certificate and key and the trusted server certificate @@ -44,23 +42,41 @@ spec: On Docker, Podman, and Linux, the value is the name of a directory under `input/certs/` in the current namespace. + description: |- + A link is a channel for communication between sites. + Links carry application connections and requests. A set of linked + sites constitutes a network. + + A Link resource specifies 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 + use an AccessToken to obtain a link. status: include_properties: [status/*] properties: - name: status + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. - name: message + description: |- + A human-readable status message. Error messages are reported here. - name: remoteSiteId - description: | + description: |- The unique ID of the site linked to. - name: remoteSiteName - description: | + description: |- The name of the site linked to. - name: conditions - description: | - @description@ + description: |- + A set of named conditions describing the current state of the resource. - - `Configured`: The link configuration has been applied to - the router. + - `Configured`: The link configuration has been applied to the router. - `Operational`: The link to the remote site is active. - - `Ready`: The link is ready to use. All other conditions - are true. + - `Ready`: The link is ready for use. All other conditions are true. diff --git a/config/resources/listener.yaml b/config/resources/listener.yaml index 920bbda0..8bd060f7 100644 --- a/config/resources/listener.yaml +++ b/config/resources/listener.yaml @@ -1,14 +1,13 @@ name: Listener related_resources: [connector] links: [skupper/service-exposure] -description: | - A listener binds a local connection endpoint to - [connectors](connector.html) in remote [sites](site.html). - Listeners and connectors are matched by routing key. +description: |- + A listener binds a local connection endpoint to connectors in remote sites. + Listeners and connector are matched by routing key. - A Listener resource specifies 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 specifies a host and port for accepting connections + from local client. 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 @@ -31,43 +30,43 @@ spec: - name: routingKey updatable: true related_concepts: [routing-key] - description: | - The identifier used to route traffic from listeners to - connectors. To enable connecting to a service at a - remote site, the local listener and the remote connector - must have matching routing keys. + description: |- + The identifier to route traffic from listeners to connectors. To + enable connecting to a service at a remote site, the local listener + and the remote connector must have matching routingKeys. - name: host updatable: true - description: | - The hostname or IP address of the local listener. Clients - at this site use the listener host and port to - establish connections to the remote service. + description: |- + The hostname or IP address of the local listener. Clients at this + site use the listener host and port to establish connections to the + remote service. - name: port updatable: true - description: | - The port of the local listener. Clients at this site use - the listener host and port to establish connections to - the remote service. + description: |- + The port of the local listener. Clients at this site use the listener + host and port to establish connections to the remote service. - name: exposePodsByName type: boolean group: advanced platforms: [Kubernetes] links: [skupper/individual-pod-services] - description: | - If true, expose each pod as an individual service. + description: |- + If true, expose each pod as an individual service. This allows individual + pods to be directly connected across a network. The pod names will be used + to create each service. - name: tlsCredentials group: advanced - links: [skupper/application-tls, kubernetes/tls-secrets, skupper/system-tls-credentials] - description: | - The name of a bundle of TLS certificates used for secure - client-to-router communication. The bundle contains the - server certificate and key. It optionally includes the - trusted client certificate (usually a CA) for mutual TLS. + links: [skupper/application-tls, kubernetes/tls-secrets, + skupper/system-tls-credentials] + description: |- + The name of a bundle of TLS certificates used for secure client-to-router + communication. The bundle contains the server certificate and key. It + optionally includes the trusted client certificate (usually a CA) for + mutual TLS. - On Kubernetes, the value is the name of a Secret in the - current namespace. On Docker, Podman, and Linux, the value is - the name of a directory under `input/certs/` in the current - namespace. + On Kubernetes, the value is the name of a Secret in the current namespace. + On Docker, Podman, and Linux, the value is the name of a directory under + input/certs/ in the current namespace. - name: type hidden: true group: advanced @@ -75,30 +74,39 @@ spec: description: | The listener type. - name: settings - description: | - @description@ + description: |- + A map containing additional settings. Each map entry has a string name and a string value. + + **Note:** In general, we recommend not changing settings from + their default values. + description: |- + A listener binds a local connection endpoint to connectors in remote sites. + Listeners and connector are matched by routing key. - - `observer`: Set the protocol observer used to generate - traffic metrics.
- Default: `auto`. Choices: `auto`, `none`, `http1`, `http2`. + A Listener resource specifies a host and port for accepting connections + from local client. To expose a multi-port service, create multiple listeners + with the same host value. status: include_properties: [status/*] properties: - name: status + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. - name: message + description: |- + A human-readable status message. Error messages are reported here. - name: hasMatchingConnector type: boolean related_concepts: [routing-key] - description: | - True if there is at least one connector with a matching - routing key (usually in a remote site). + description: |- + True if there is at least one connector with a matching routing key (usually in a remote site). - name: conditions - description: | - @description@ + description: |- + A set of named conditions describing the current state of the resource. - - `Configured`: The listener configuration has been applied - to the router. - - `Matched`: There is at least one connector corresponding to - this listener. - - `Ready`: The listener is ready to use. All other conditions - are true. + - `Configured`: The listener configuration has been applied to the router. + - `Operational`: There is at least one connector corresponding to this listener. + - `Ready`: The listener is ready for use. All other conditions are true. diff --git a/config/resources/router-access.yaml b/config/resources/router-access.yaml index 8ae7db27..31eb20ec 100644 --- a/config/resources/router-access.yaml +++ b/config/resources/router-access.yaml @@ -1,7 +1,7 @@ name: RouterAccess related_resources: [site, link] links: [skupper/site-linking] -description: | +description: |- Configuration for secure access to the site router. The configuration includes TLS credentials and router ports. The RouterAccess resource is used to implement link access for sites. @@ -11,13 +11,14 @@ spec: include_properties: [settings] properties: - name: roles - description: | + description: |- The named interfaces by which a router can be accessed. These include "inter-router" for links between interior routers and "edge" for links from edge routers to interior routers. - name: tlsCredentials - links: [skupper/router-tls, kubernetes/tls-secrets, skupper/system-tls-credentials] - description: | + links: [skupper/router-tls, kubernetes/tls-secrets, + skupper/system-tls-credentials] + description: |- The name of a bundle of TLS certificates used for mutual TLS router-to-router communication. The bundle contains the server certificate and key and the trusted client certificate @@ -29,7 +30,15 @@ spec: On Docker, Podman, and Linux, the value is the name of a directory under `input/certs/` in the current namespace. - name: generateTlsCredentials + description: |- + When set, Skupper generates the TLS credentials to be + stored in the Secret specified by `tlsCredentials`. See + also `issuer`. - name: issuer + description: |- + The name of the Kubernetes Secret containing the signing CA + used to generate TLS certificates for the RouterAccess when + `generateTlsCredentials` is set. - name: accessType platforms: [Kubernetes] default: | @@ -40,10 +49,19 @@ spec: description: Use an OpenShift route. _OpenShift only._ - name: loadbalancer description: Use a Kubernetes load balancer. + description: |- + Configures the access type for the router endpoints. + Available access types and the default selection is + configured on the Skupper controller for Kubernetes. + + The options available by default are: + - `local`: No external ingress. Implies a Kubernetes Service with type CluterIP. + - `route`: Exposed via an OpenShift Route. + - `loadbalancer`: Exposed via a Kubernetes Service with type LoadBalancer. - name: bindHost default: 0.0.0.0 platforms: [Docker, Podman, Linux] - description: | + description: |- The hostname or IP address of the network interface to bind to. By default, Skupper binds all the interfaces on the host. - name: subjectAlternativeNames @@ -51,24 +69,33 @@ spec: default: | _The current hostname and the IP address of each bound network interface_ - description: | + description: |- The hostnames and IPs secured by the router TLS certificate. + description: |- + Configuration for secure access to the site router. The + configuration includes TLS credentials and router ports. The + RouterAccess resource is used to implement link access for sites. status: include_properties: [status/*] properties: - name: status + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. - name: message + description: |- + A human-readable status message. Error messages are reported here. - name: conditions - description: | - @description@ + description: |- + A set of named conditions describing the current state of the resource. - - `Configured`: The router access configuration has been applied to - the router. - - `Resolved`: The connection endpoints are available. - - `Ready`: The router access is ready to use. All other - conditions are true. + - `Configured`: The output resources for this resource have been created. + - `Resolved`: The connection endpoints are available. + - `Ready`: The router access is ready for use. All other conditions are true. - name: endpoints group: advanced - description: | + description: |- An array of connection endpoints. Each item has a name, host, port, and group. diff --git a/config/resources/site.yaml b/config/resources/site.yaml index b1d1c52a..fb580ddf 100644 --- a/config/resources/site.yaml +++ b/config/resources/site.yaml @@ -1,12 +1,12 @@ name: Site related_resources: [link] links: [skupper/site-configuration] -description: | +description: |- A site is a place on the network where application workloads are - running. Sites are joined by [links](link.html). + running. Sites are joined by links. - The Site resource is the basis for site configuration. It is the - parent of all Skupper resources in its namespace. There can be only + 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 @@ -29,6 +29,13 @@ metadata: include_properties: [metadata/*] properties: - name: name + description: |- + A site is a place on the network where application workloads are + running. Sites are joined by links. + + 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. spec: include_properties: [settings] properties: @@ -38,12 +45,18 @@ spec: updatable: true related_concepts: [link] links: [skupper/site-linking] - description: | - Configure external access for links from remote sites. + description: |- + Configure external access for links from remote sites. When + set, implies a RouterAccess resource with accessType set + according to the linkAccess value. Sites and links are the basis for creating application - networks. In a simple two-site network, at least one of - the sites must have link access enabled. + networks. In a simple two-site network, at least one of the + sites must have link access enabled. Choices include: + - `none`: No linking to this site is enabled. + - `default`: Use the default link access for the current platform. For OpenShift, the default is `route`. For other Kubernetes flavors, the default is `loadbalancer`. + - `route`: Use an OpenShift route. + - `loadbalancer`: Use a Kubernetes load balancer. choices: - name: none description: No linking to this site is permitted. @@ -61,97 +74,99 @@ spec: updatable: true platforms: [Kubernetes] links: [skupper/high-availability] - description: | - Configure the site for high availability (HA). HA sites + description: |- + Configure the site for high availability (HA). HA sites have two active routers. Note that Skupper routers are stateless, and they restart - after failure. This already provides a high level of - availability. Enabling HA goes further and reduces the + after failure. This already provides a high level of + availability. Enabling HA goes further and reduces the window of downtime caused by restarts. + + By default, Pod anti-affinity will be configured on the router + Deployments when HA is enabled. To overwrite this behavior + see the `disable-anti-affinity` Site setting. - name: defaultIssuer group: advanced default: skupper-site-ca updatable: true platforms: [Kubernetes] links: [skupper/router-tls, kubernetes/tls-secrets] - description: | - The name of a Kubernetes secret containing the signing CA - used to generate a certificate from a token. A secret is - generated if none is specified. + description: |- + Advanced. The name of a Kubernetes secret containing the + signing CA used to generate a certificate from a token. A + secret is generated if none is specified. This issuer is used by AccessGrant and RouterAccess if a - specific issuer is not set. + specific issuer is not set. Defaults to `skupper-site-ca` - name: edge group: advanced type: boolean links: [skupper/large-networks] - description: | - Configure the site to operate in edge mode. Edge sites - cannot accept links from remote sites. + description: |- + Advanced. Configure the site to operate in edge mode. Edge + sites cannot accept links from remote sites. Edge mode can help you scale your network to large numbers - of sites. However, for networks with 16 or fewer sites, + of sites. However, for networks with 16 or fewer sites, there is little benefit. Currently, edge sites cannot also have HA enabled. - - - name: serviceAccount group: advanced default: _Generated_ platforms: [Kubernetes] links: [kubernetes/service-accounts] - description: | - The name of the Kubernetes service account under which to run - the Skupper router. A service account is generated if none is - specified. + description: |- + Advanced. The name of the Kubernetes service account under + which to run the Skupper router. A service account is + generated if none is specified. - name: settings - description: | - @description@ + description: |- + Advanced. A map containing additional settings. Each map + entry has a string name and a string value. + + **Note:** In general, we recommend not changing `settings` + from their default values. - - `routerDataConnections`: Set the number of data - connections the router uses when linking to other - routers.
- Default: *Computed based on the number of router worker - threads. Minimum 2.* - - `routerLogging`: Set the router logging level.
- Default: `info`. Choices: `info`, `warning`, `error`. + - `routerDataConnections`: Set the number of router worker threads. Minimum 2. + - `routerLogging`: Set the number of router logging level. Options are "info", "warning", "error". + - `disable-anti-affinity`: Set to "true" in order to prevent skupper from specifying router pod affinity. + - `size`: The desired site sizing profile to use for constraining pod resources. Corresponds to a ConfigMap with matching `skupper.io/site-sizing` label. + - `tls-prior-valid-revisions`: Set the number of revisions to TLS Secrets backing Site Link connections that are permissible to hold open to preserve established service connections. An unsigned integer defaults to 1. Set to 0 to immediately disrupt connections secured with old TLS configurations. status: include_properties: [status/*] properties: - name: status + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. - name: message + description: |- + A human-readable status message. Error messages are reported here. - name: conditions group: advanced - description: | - @description@ + description: |- + A set of named conditions describing the current state of the resource. - - `Configured`: The output resources for this resource have - been created. + - `Configured`: The output resources for this resource have been created. - `Running`: There is at least one router pod running. - - `Resolved`: The hostname or IP address for link access is - available. - - `Ready`: The site is ready for use. All other conditions - are true. + - `Resolved`: The hostname or IP address for link access is available. + - `Ready`: The site is ready for use. All other conditions are true. - name: defaultIssuer group: advanced platforms: [Kubernetes] links: [skupper/router-tls, kubernetes/tls-secrets] - description: | - The name of the Kubernetes secret containing the active - default signing CA. + description: |- + The name of the Kubernetes secret containing the active default signing CA. - name: endpoints group: advanced related_concepts: [link] links: [skupper/site-linking] - description: | - An array of connection endpoints. Each item has a name, host, - port, and group. - - These include connection endpoints for link access. + description: |- + An array of connection endpoints. Each item has a name, host, port, and group. These include connection endpoints for link access. notes: | Why is this here in status? Does it duplicate what we have in RouterAccess? - name: network diff --git a/crds/skupper_access_grant_crd.yaml b/crds/skupper_access_grant_crd.yaml index 47ad694a..76a8d8f8 100644 --- a/crds/skupper_access_grant_crd.yaml +++ b/crds/skupper_access_grant_crd.yaml @@ -10,21 +10,46 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + Permission to redeem access tokens for links to the local site. + A remote site can use a token containing the grant URL and secret + code to obtain a certificate signed by the grant's certificate authority (CA), + within a certain expiration window and for a limited number of redemptions. + + The code, url, and ca properties of the resource status are used to generate access tokens from the grant. type: object properties: spec: type: object properties: redemptionsAllowed: + description: |- + The maximum number of times an access token for this grant can be redeemed. + The default value is `1`. type: integer expirationWindow: + description: |- + The period of time in which an access token for this grant can be redeemed. + The default value is `15m`. type: string format: duration code: + description: |- + Advanced. The secret code to use to authenticate access tokens submitted for redemption. + If not set, a value is generated and placed in the code status property. type: string issuer: + description: |- + Advanced. The name of a Kubernetes secret used to generate a certificate when redeeming a token for this grant. + If not set, `defaultIssuer` on the Site resource is used. type: string settings: + description: |- + Advanced. A map containing additional settings. Each map + entry has a string name and a string value. + + **Note:** In general, we recommend not changing `settings` + from their default values. type: object additionalProperties: type: string @@ -32,21 +57,44 @@ spec: type: object properties: url: + description: |- + The URL of the token-redemption service for this grant. type: string code: + description: |- + The secret code used to authenticate access tokens submitted for redemption. type: string ca: + description: |- + The trusted server certificate of the token-redemption service for this grant. type: string redemptions: + description: |- + The number of times a token for this grant has been redeemed. type: integer expirationTime: + description: |- + The point in time when the grant expires. type: string format: date-time status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. type: string message: + description: |- + A human-readable status message. Error messages are reported here. type: string conditions: + description: |- + A set of named conditions describing the current state of the resource. + + - `Processed`: The controller has accepted the grant. + - `Resolved`: The grant service is available to process tokens for this grant. + - `Ready`: The grant is ready to use. All other conditions are true. type: array items: type: object @@ -74,7 +122,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -92,11 +140,11 @@ spec: - name: Redemptions Made type: integer description: The number of times an access token originating from this grant has been redeemed - jsonPath: .status.redeemed + jsonPath: .status.redemptions - name: Expiration type: string description: When the grant will expire - jsonPath: .status.expiration + jsonPath: .status.expirationTime - name: Status type: string description: The status of the grant @@ -110,3 +158,6 @@ spec: plural: accessgrants singular: accessgrant kind: AccessGrant + shortNames: + - grant + - gr diff --git a/crds/skupper_access_token_crd.yaml b/crds/skupper_access_token_crd.yaml index 55a29c18..4eceea8f 100644 --- a/crds/skupper_access_token_crd.yaml +++ b/crds/skupper_access_token_crd.yaml @@ -10,20 +10,38 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + A short-lived credential used to create a link between sites. + An access token contains the URL and secret code of a corresponding access grant. + **Note:** Access tokens are typically issued and redeemed using the Skupper CLI. type: object properties: spec: type: object properties: url: + description: |- + The URL of the grant service at the remote site. type: string code: + description: |- + The secret code used to authenticate the token when submitted for redemption. type: string ca: + description: |- + The trusted server certificate of the grant service at the remote site. type: string linkCost: + description: |- + The link cost to use when creating the link. type: integer settings: + description: |- + Advanced. A map containing additional settings. Each map + entry has a string name and a string value. + + **Note:** In general, we recommend not changing settings + from their default values. type: object additionalProperties: type: string @@ -35,13 +53,26 @@ spec: type: object properties: redeemed: + description: |- + True if the token has been redeemed. Once a token is redeemed, it cannot be used again. type: boolean status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. type: string message: + description: |- + A human-readable status message. Error messages are reported here. type: string conditions: type: array + description: |- + A set of named conditions describing the current state of the resource. + + - `Redeemed`: The token has been exchanged for a link. items: type: object properties: @@ -68,7 +99,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -100,3 +131,6 @@ spec: plural: accesstokens singular: accesstoken kind: AccessToken + shortNames: + - token + - to diff --git a/crds/skupper_attached_connector_binding_crd.yaml b/crds/skupper_attached_connector_binding_crd.yaml index 69d21c62..e361ebc5 100644 --- a/crds/skupper_attached_connector_binding_crd.yaml +++ b/crds/skupper_attached_connector_binding_crd.yaml @@ -10,18 +10,33 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + An attached connector binding is a binding to an attached connector in a peer namespace that allows you to + bring a workload into your existing VAN without creating a separate site or establishing inter-site links. + The name of this resource must be the same as that of the associated AttachedConnector resource in the peer + namespace. type: object properties: spec: type: object properties: connectorNamespace: + description: |- + The name of the namespace where the associated AttachedConnector is located. type: string routingKey: + description: |- + The identifier used to route traffic from listeners to connectors. To expose a local workload to a + remote site, the remote listener and the local connector must have matching routing keys. type: string exposePodsByName: + description: |- + If true, expose each pod as an individual service. type: boolean settings: + description: |- + Advanced. A map containing additional settings. Each map entry has a string name and a string value. + **Note**: In general, we recommend not changing settings from their default values. type: object additionalProperties: type: string @@ -32,8 +47,19 @@ spec: type: object properties: status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See message for more information. + - `Ready`: The resource is ready to use. + type: string + message: + description: |- + A human-readable status message. Error messages are reported here. type: string conditions: + description: |- + A set of named conditions describing the current state of the resource. type: array items: type: object @@ -61,7 +87,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -70,6 +96,8 @@ spec: - status - type hasMatchingListener: + description: |- + Whether there is at least one listener in the network with a matching routing key. type: boolean subresources: status: {} @@ -87,7 +115,7 @@ spec: description: The status of the connector jsonPath: .status.status - name: Has Matching Listener - type: integer + type: boolean description: Whether there is at least one listener in the network with a matching routing key. jsonPath: .status.hasMatchingListener scope: Namespaced @@ -95,3 +123,5 @@ spec: plural: attachedconnectorbindings singular: attachedconnectorbinding kind: AttachedConnectorBinding + shortNames: + - acnrb diff --git a/crds/skupper_attached_connector_crd.yaml b/crds/skupper_attached_connector_crd.yaml index 59d474f8..c4fe4004 100644 --- a/crds/skupper_attached_connector_crd.yaml +++ b/crds/skupper_attached_connector_crd.yaml @@ -10,24 +10,48 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + An attached connector is a connector in a peer namespace that allows you to bring a workload into your existing VAN without creating a separate site or establishing inter-site links. + The name of this resource must be the same as that of the associated AttachedConnectorBinding resource in the site namespace. type: object properties: spec: type: object properties: siteNamespace: + description: |- + The name of the namespace in which the site this connector should be attached to is defined. type: string port: + description: |- + The port on the target server to connect to. type: integer selector: + description: |- + A Kubernetes label selector for specifying target server pods. It uses = syntax. + On Kubernetes, either selector or host is required. type: string tlsCredentials: + description: |- + Advanced. The name of a bundle of TLS certificates used for secure router-to-server communication. The bundle contains the trusted server certificate (usually a CA). It optionally includes a client certificate and key for mutual TLS. + On Kubernetes, the value is the name of a Secret in the current namespace. On Docker, Podman, and Linux, the value is the name of a directory under input/certs/ in the current namespace. type: string + useClientCert: + type: boolean + description: |- + Advanced. Send the client certificate when connecting in order to enable mutual TLS. Default value is false. type: type: string + description: |- + Selected protocol for service networking. By default, its value is TCP, the only option available. includeNotReadyPods: + description: |- + Advanced. If true, include server pods in the NotReady state. By default it is false. type: boolean settings: + description: |- + Advanced. A map containing additional settings. Each map entry has a string name and a string value. + Note: In general, we recommend not changing settings from their default values. type: object additionalProperties: type: string @@ -39,8 +63,19 @@ spec: type: object properties: status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See message for more information. + - `Ready`: The resource is ready to use. + type: string + message: + description: |- + A human-readable status message. Error messages are reported here. type: string conditions: + description: |- + A set of named conditions describing the current state of the resource. type: array items: type: object @@ -68,7 +103,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -109,3 +144,5 @@ spec: plural: attachedconnectors singular: attachedconnector kind: AttachedConnector + shortNames: + - acnr diff --git a/crds/skupper_certificate_crd.yaml b/crds/skupper_certificate_crd.yaml new file mode 100644 index 00000000..17d2cb30 --- /dev/null +++ b/crds/skupper_certificate_crd.yaml @@ -0,0 +1,121 @@ +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: certificates.skupper.io +spec: + group: skupper.io + versions: + - name: v2alpha1 + served: true + storage: true + schema: + openAPIV3Schema: + description: "An internal resource used to indicate TLS credentials to be created" + type: object + properties: + spec: + type: object + properties: + ca: + type: string + subject: + type: string + hosts: + type: array + items: + type: string + client: + type: boolean + server: + type: boolean + signing: + type: boolean + settings: + type: object + additionalProperties: + type: string + required: + - ca + - subject + status: + type: object + properties: + status: + type: string + message: + type: string + conditions: + type: array + items: + type: object + properties: + lastTransitionTime: + format: date-time + type: string + message: + maxLength: 32768 + type: string + observedGeneration: + format: int64 + minimum: 0 + type: integer + reason: + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + enum: + - "True" + - "False" + - Unknown + type: string + type: + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + expiration: + type: string + format: date-time + subresources: + status: {} + additionalPrinterColumns: + - name: CA + type: string + description: Identifies the CA to be used in signing the certificate + jsonPath: .spec.ca + - name: Server + type: boolean + description: Whether or not the certificate is valid for use as a server + jsonPath: .spec.server + - name: Client + type: boolean + description: Whether or not the certificate is valid for use as a client + jsonPath: .spec.client + - name: Signing + type: boolean + description: Whether or not the certificate is valid for use as a CA + jsonPath: .spec.signing + - name: Status + type: string + description: The status of the certificate + jsonPath: .status.status + - name: Expiration + type: string + description: The expiration of the certificate if relevant + jsonPath: .status.expiration + - name: Message + type: string + description: Any relevant human readable message + jsonPath: .status.message + scope: Namespaced + names: + plural: certificates + singular: certificate + kind: Certificate diff --git a/crds/skupper_connector_crd.yaml b/crds/skupper_connector_crd.yaml index faa16f50..b49ee715 100644 --- a/crds/skupper_connector_crd.yaml +++ b/crds/skupper_connector_crd.yaml @@ -10,32 +10,82 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + A connector binds a local workload to listeners in remote sites. Listeners + and connectors are matched by routing key. + + On Kubernetes, a Connector resource has a selector and port for specifying + workload pods. + + 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. type: object properties: spec: type: object properties: routingKey: + description: |- + The identifier used to route traffic from listeners to connectors. + To expose a local workload to a remote site, the remote listener and + the local connector must have matching routing keys. type: string port: + description: |- + The port on the target server to connect to. type: integer selector: + description: |- + A Kubernetes label selector for specifying target server pods. It uses + = syntax. + + On Kubernetes, either selector or host is required. type: string host: + description: |- + The hostname or IP address of the server. This is an alternative to + selector for specifying the target server. + + On Kubernetes, either selector or host is required. + + On Docker, Podman, or Linux, host is required. type: string tlsCredentials: + description: |- + The name of a bundle of TLS certificates used for secure router-to-server + communication. The bundle contains the trusted server certificate + (usually a CA). It optionally includes a client certificate and key for + mutual TLS. + + On Kubernetes, the value is the name of a Secret in the current namespace. + On Docker, Podman, and Linux, the value is the name of a directory under + input/certs/ in the current namespace. type: string useClientCert: + description: |- + Send the client certificate when connecting in order to enable mutual TLS. type: boolean verifyHostname: + description: |- + If true, require that the hostname of the server connected to matches the + hostname in the server's certificate. type: boolean type: type: string includeNotReadyPods: + description: |- + If true, include server pods in the NotReady state. type: boolean exposePodsByName: + description: |- + If true, expose each pod as an individual service. type: boolean settings: + description: |- + A map containing additional settings. Each map entry has a string name and a + string value. + + Note: In general, we recommend not changing settings from their default values. type: object additionalProperties: type: string @@ -51,11 +101,23 @@ spec: type: object properties: status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. type: string message: + description: |- + A human-readable status message. Error messages are reported here. type: string conditions: type: array + description: |- + A set of named conditions describing the current state of the resource. + - `Configured`: The connector configuration has been applied to the router. + - `Matched`: There is at least one listener corresponding to this connector. + - `Ready`: The connector is ready to use. All other conditions are true. items: type: object properties: @@ -82,7 +144,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -90,6 +152,10 @@ spec: - reason - status - type + hasMatchingListener: + description: |- + True if there is at least one listener with a matching routing key (usually in a remote site). + type: boolean selectedPods: type: array items: @@ -99,8 +165,6 @@ spec: type: string ip: type: string - hasMatchingListener: - type: boolean subresources: status: {} additionalPrinterColumns: @@ -137,3 +201,5 @@ spec: plural: connectors singular: connector kind: Connector + shortNames: + - cnr diff --git a/crds/skupper_link_crd.yaml b/crds/skupper_link_crd.yaml index e82e2556..218985fe 100644 --- a/crds/skupper_link_crd.yaml +++ b/crds/skupper_link_crd.yaml @@ -10,12 +10,28 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + A link is a channel for communication between sites. + Links carry application connections and requests. A set of linked + sites constitutes a network. + + A Link resource specifies 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 + use an AccessToken to obtain a link. type: object properties: spec: type: object properties: endpoints: + description : |- + An array of connection endpoints. Each item has a name, host, + port, and group. type: array items: type: object @@ -29,10 +45,29 @@ spec: group: type: string tlsCredentials: + description: |- + The name of a bundle of certificates used for mutual TLS + router-to-router communication. The bundle contains the + client certificate and key and the trusted server certificate + (usually a CA). + + On Kubernetes, the value is the name of a Secret in the + current namespace. + + On Docker, Podman, and Linux, the value is the name of a + directory under `input/certs/` in the current namespace. type: string cost: + description: |- + The configured routing cost of sending traffic over the link. type: integer settings: + description: |- + A map containing additional settings. Each map entry has a + string name and a string value. + + **Note:** In general, we recommend not changing `settings` from + their default values. type: object additionalProperties: type: string @@ -42,15 +77,32 @@ spec: type: object properties: status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. type: string message: + description: |- + A human-readable status message. Error messages are reported here. type: string remoteSiteId: + description: |- + The unique ID of the site linked to. type: string remoteSiteName: + description: |- + The name of the site linked to. type: string conditions: type: array + description: |- + A set of named conditions describing the current state of the resource. + + - `Configured`: The link configuration has been applied to the router. + - `Operational`: The link to the remote site is active. + - `Ready`: The link is ready for use. All other conditions are true. items: type: object properties: @@ -77,7 +129,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -105,3 +157,5 @@ spec: plural: links singular: link kind: Link + shortNames: + - ln diff --git a/crds/skupper_listener_crd.yaml b/crds/skupper_listener_crd.yaml index 9015b970..f7079e5f 100644 --- a/crds/skupper_listener_crd.yaml +++ b/crds/skupper_listener_crd.yaml @@ -10,24 +10,60 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + A listener binds a local connection endpoint to connectors in remote sites. + Listeners and connector are matched by routing key. + + A Listener resource specifies a host and port for accepting connections + from local client. To expose a multi-port service, create multiple listeners + with the same host value. type: object properties: spec: type: object properties: routingKey: + description: |- + The identifier to route traffic from listeners to connectors. To + enable connecting to a service at a remote site, the local listener + and the remote connector must have matching routingKeys. type: string host: + description: |- + The hostname or IP address of the local listener. Clients at this + site use the listener host and port to establish connections to the + remote service. type: string port: + description: |- + The port of the local listener. Clients at this site use the listener + host and port to establish connections to the remote service. type: integer tlsCredentials: + description: |- + The name of a bundle of TLS certificates used for secure client-to-router + communication. The bundle contains the server certificate and key. It + optionally includes the trusted client certificate (usually a CA) for + mutual TLS. + + On Kubernetes, the value is the name of a Secret in the current namespace. + On Docker, Podman, and Linux, the value is the name of a directory under + input/certs/ in the current namespace. type: string type: type: string exposePodsByName: + description: |- + If true, expose each pod as an individual service. This allows individual + pods to be directly connected across a network. The pod names will be used + to create each service. type: boolean settings: + description: |- + A map containing additional settings. Each map entry has a string name and a string value. + + **Note:** In general, we recommend not changing settings from + their default values. type: object additionalProperties: type: string @@ -39,11 +75,24 @@ spec: type: object properties: status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. type: string message: + description: |- + A human-readable status message. Error messages are reported here. type: string conditions: type: array + description: |- + A set of named conditions describing the current state of the resource. + + - `Configured`: The listener configuration has been applied to the router. + - `Operational`: There is at least one connector corresponding to this listener. + - `Ready`: The listener is ready for use. All other conditions are true. items: type: object properties: @@ -70,7 +119,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -79,6 +128,8 @@ spec: - status - type hasMatchingConnector: + description: |- + True if there is at least one connector with a matching routing key (usually in a remote site). type: boolean subresources: status: {} @@ -102,7 +153,7 @@ spec: - name: Has Matching Connector type: boolean description: Whether there is at least one connector in the network with a matching routing key. - jsonPath: .status.hasMtchingConnector + jsonPath: .status.hasMatchingConnector - name: Message type: string description: Any human readable message relevant to the listener @@ -112,3 +163,5 @@ spec: plural: listeners singular: listener kind: Listener + shortNames: + - lnr diff --git a/crds/skupper_router_access_crd.yaml b/crds/skupper_router_access_crd.yaml index f60a19b2..63e435b0 100644 --- a/crds/skupper_router_access_crd.yaml +++ b/crds/skupper_router_access_crd.yaml @@ -10,35 +10,86 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + Configuration for secure access to the site router. The + configuration includes TLS credentials and router ports. The + RouterAccess resource is used to implement link access for sites. type: object properties: spec: type: object properties: roles: + description: |- + The named interfaces by which a router can be accessed. These + include "inter-router" for links between interior routers and + "edge" for links from edge routers to interior routers. type: array items: type: object properties: name: + description: The role name. Either "inter-router" or "edge". type: string port: + description: The port for the router to bind. Must not conflict with another role. type: integer + required: + - name generateTlsCredentials: + description: |- + When set, Skupper generates the TLS credentials to be + stored in the Secret specified by `tlsCredentials`. See + also `issuer`. type: boolean issuer: type: string + description: |- + The name of the Kubernetes Secret containing the signing CA + used to generate TLS certificates for the RouterAccess when + `generateTlsCredentials` is set. accessType: + description: |- + Configures the access type for the router endpoints. + Available access types and the default selection is + configured on the Skupper controller for Kubernetes. + + The options available by default are: + - `local`: No external ingress. Implies a Kubernetes Service with type CluterIP. + - `route`: Exposed via an OpenShift Route. + - `loadbalancer`: Exposed via a Kubernetes Service with type LoadBalancer. type: string tlsCredentials: + description: |- + The name of a bundle of TLS certificates used for mutual TLS + router-to-router communication. The bundle contains the + server certificate and key and the trusted client certificate + (usually a CA). + + On Kubernetes, the value is the name of a Secret in the + current namespace. + + On Docker, Podman, and Linux, the value is the name of a + directory under `input/certs/` in the current namespace. type: string bindHost: + description: |- + The hostname or IP address of the network interface to bind + to. By default, Skupper binds all the interfaces on the host. type: string subjectAlternativeNames: type: array + description: |- + The hostnames and IPs secured by the router TLS certificate. items: type: string settings: + description: |- + Advanced. A map containing additional settings. Each map + entry has a string name and a string value. + + **Note:** In general, we recommend not changing `settings` + from their default values. type: object additionalProperties: type: string @@ -49,11 +100,24 @@ spec: type: object properties: status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. type: string message: + description: |- + A human-readable status message. Error messages are reported here. type: string conditions: type: array + description: |- + A set of named conditions describing the current state of the resource. + + - `Configured`: The output resources for this resource have been created. + - `Resolved`: The connection endpoints are available. + - `Ready`: The router access is ready for use. All other conditions are true. items: type: object properties: @@ -80,7 +144,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -90,6 +154,9 @@ spec: - type endpoints: type: array + description: |- + An array of connection endpoints. Each item has a name, host, + port, and group. items: type: object properties: diff --git a/crds/skupper_secured_access_crd.yaml b/crds/skupper_secured_access_crd.yaml new file mode 100644 index 00000000..9946854d --- /dev/null +++ b/crds/skupper_secured_access_crd.yaml @@ -0,0 +1,125 @@ +apiVersion: apiextensions.k8s.io/v1 +kind: CustomResourceDefinition +metadata: + name: securedaccesses.skupper.io +spec: + group: skupper.io + versions: + - name: v2alpha1 + served: true + storage: true + schema: + openAPIV3Schema: + description: "An internal resource used to create secure access to pods" + type: object + properties: + spec: + type: object + properties: + ports: + type: array + items: + type: object + properties: + name: + type: string + port: + type: integer + targetPort: + type: integer + protocol: + type: string + required: + - name + - port + selector: + type: object + additionalProperties: + type: string + issuer: + type: string + certificate: + type: string + accessType: + type: string + settings: + type: object + additionalProperties: + type: string + required: + - selector + - ports + status: + type: object + properties: + endpoints: + type: array + items: + type: object + properties: + name: + type: string + host: + type: string + port: + type: string + group: + type: string + ca: + type: string + status: + type: string + message: + type: string + conditions: + type: array + items: + type: object + properties: + lastTransitionTime: + format: date-time + type: string + message: + maxLength: 32768 + type: string + observedGeneration: + format: int64 + minimum: 0 + type: integer + reason: + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + enum: + - "True" + - "False" + - Unknown + type: string + type: + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + subresources: + status: {} + additionalPrinterColumns: + - name: Status + type: string + description: The status of the secured access + jsonPath: .status.status + - name: Message + type: string + description: Any relevant human readable message + jsonPath: .status.message + scope: Namespaced + names: + plural: securedaccesses + singular: securedaccess + kind: SecuredAccess diff --git a/crds/skupper_site_crd.yaml b/crds/skupper_site_crd.yaml index ce278161..a48cd71f 100644 --- a/crds/skupper_site_crd.yaml +++ b/crds/skupper_site_crd.yaml @@ -10,22 +10,85 @@ spec: storage: true schema: openAPIV3Schema: + description: |- + A site is a place on the network where application workloads are + running. Sites are joined by links. + + 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. type: object properties: spec: type: object properties: serviceAccount: + description: |- + Advanced. The name of the Kubernetes service account under + which to run the Skupper router. A service account is + generated if none is specified. type: string linkAccess: + description: |- + Configure external access for links from remote sites. When + set, implies a RouterAccess resource with accessType set + according to the linkAccess value. + + Sites and links are the basis for creating application + networks. In a simple two-site network, at least one of the + sites must have link access enabled. Choices include: + - `none`: No linking to this site is enabled. + - `default`: Use the default link access for the current platform. For OpenShift, the default is `route`. For other Kubernetes flavors, the default is `loadbalancer`. + - `route`: Use an OpenShift route. + - `loadbalancer`: Use a Kubernetes load balancer. type: string defaultIssuer: + description: |- + Advanced. The name of a Kubernetes secret containing the + signing CA used to generate a certificate from a token. A + secret is generated if none is specified. + + This issuer is used by AccessGrant and RouterAccess if a + specific issuer is not set. Defaults to `skupper-site-ca` type: string ha: type: boolean + description: |- + Configure the site for high availability (HA). HA sites + have two active routers. + + Note that Skupper routers are stateless, and they restart + after failure. This already provides a high level of + availability. Enabling HA goes further and reduces the + window of downtime caused by restarts. + + By default, Pod anti-affinity will be configured on the router + Deployments when HA is enabled. To overwrite this behavior + see the `disable-anti-affinity` Site setting. edge: type: boolean + description: |- + Advanced. Configure the site to operate in edge mode. Edge + sites cannot accept links from remote sites. + + Edge mode can help you scale your network to large numbers + of sites. However, for networks with 16 or fewer sites, + there is little benefit. + + Currently, edge sites cannot also have HA enabled. settings: + description: |- + Advanced. A map containing additional settings. Each map + entry has a string name and a string value. + + **Note:** In general, we recommend not changing `settings` + from their default values. + + - `routerDataConnections`: Set the number of router worker threads. Minimum 2. + - `routerLogging`: Set the number of router logging level. Options are "info", "warning", "error". + - `disable-anti-affinity`: Set to "true" in order to prevent skupper from specifying router pod affinity. + - `size`: The desired site sizing profile to use for constraining pod resources. Corresponds to a ConfigMap with matching `skupper.io/site-sizing` label. + - `tls-prior-valid-revisions`: Set the number of revisions to TLS Secrets backing Site Link connections that are permissible to hold open to preserve established service connections. An unsigned integer defaults to 1. Set to 0 to immediately disrupt connections secured with old TLS configurations. type: object additionalProperties: type: string @@ -33,13 +96,38 @@ spec: type: object properties: defaultIssuer: + description: |- + The name of the Kubernetes secret containing the active default signing CA. type: string status: + description: |- + The current state of the resource. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use. type: string message: + description: |- + A human-readable status message. Error messages are reported here. type: string + controller: + type: object + properties: + name: + type: string + namespace: + type: string + version: + type: string conditions: type: array + description: |- + A set of named conditions describing the current state of the resource. + + - `Configured`: The output resources for this resource have been created. + - `Running`: There is at least one router pod running. + - `Resolved`: The hostname or IP address for link access is available. + - `Ready`: The site is ready for use. All other conditions are true. items: type: object properties: @@ -66,7 +154,7 @@ spec: type: string type: maxLength: 316 - pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][- A-Za-z0-9_.]*)?[A-Za-z0-9])$ + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ type: string required: - lastTransitionTime @@ -75,6 +163,8 @@ spec: - status - type endpoints: + description: |- + An array of connection endpoints. Each item has a name, host, port, and group. These include connection endpoints for link access. type: array items: type: object @@ -152,3 +242,5 @@ spec: plural: sites singular: site kind: Site + shortNames: + - st diff --git a/input/commands/connector/create.md b/input/commands/connector/create.md index 663ea22c..f835605a 100644 --- a/input/commands/connector/create.md +++ b/input/commands/connector/create.md @@ -85,10 +85,9 @@ The port on the target server to connect to.
-The identifier used to route traffic from listeners to -connectors. To expose a local workload to a remote site, the -remote listener and the local connector must have matching -routing keys. +The identifier used to route traffic from listeners to connectors. +To expose a local workload to a remote site, the remote listener and +the local connector must have matching routing keys.
Default

Value of name

UpdatableTrue
diff --git a/input/commands/connector/generate.md b/input/commands/connector/generate.md index a181a7e1..b02809a7 100644 --- a/input/commands/connector/generate.md +++ b/input/commands/connector/generate.md @@ -82,10 +82,9 @@ The port on the target server to connect to.
-The identifier used to route traffic from listeners to -connectors. To expose a local workload to a remote site, the -remote listener and the local connector must have matching -routing keys. +The identifier used to route traffic from listeners to connectors. +To expose a local workload to a remote site, the remote listener and +the local connector must have matching routing keys.
Default

Value of name

UpdatableTrue
diff --git a/input/commands/connector/update.md b/input/commands/connector/update.md index cb13721e..4398d201 100644 --- a/input/commands/connector/update.md +++ b/input/commands/connector/update.md @@ -76,10 +76,9 @@ The port on the target server to connect to.
-The identifier used to route traffic from listeners to -connectors. To expose a local workload to a remote site, the -remote listener and the local connector must have matching -routing keys. +The identifier used to route traffic from listeners to connectors. +To expose a local workload to a remote site, the remote listener and +the local connector must have matching routing keys.
Default

Value of name

UpdatableTrue
diff --git a/input/commands/link/generate.md b/input/commands/link/generate.md index f4e49e56..bd405dba 100644 --- a/input/commands/link/generate.md +++ b/input/commands/link/generate.md @@ -86,8 +86,7 @@ generated if none is provided.
-The configured routing cost of sending traffic over -the link. +The configured routing cost of sending traffic over the link.
Default1
See alsoLoad balancing
diff --git a/input/commands/link/update.md b/input/commands/link/update.md index 06ac8ba6..6b06245d 100644 --- a/input/commands/link/update.md +++ b/input/commands/link/update.md @@ -55,8 +55,7 @@ The name of the resource to be updated.
-The configured routing cost of sending traffic over -the link. +The configured routing cost of sending traffic over the link.
Default1
See alsoLoad balancing
diff --git a/input/commands/listener/create.md b/input/commands/listener/create.md index 5b961dd1..f3f0354b 100644 --- a/input/commands/listener/create.md +++ b/input/commands/listener/create.md @@ -65,9 +65,8 @@ The name is the default routing key and host if the
-The port of the local listener. Clients at this site use -the listener host and port to establish connections to -the remote service. +The port of the local listener. Clients at this site use the listener +host and port to establish connections to the remote service.
UpdatableTrue
@@ -82,10 +81,9 @@ the remote service.
-The identifier used to route traffic from listeners to -connectors. To enable connecting to a service at a -remote site, the local listener and the remote connector -must have matching routing keys. +The identifier to route traffic from listeners to connectors. To +enable connecting to a service at a remote site, the local listener +and the remote connector must have matching routingKeys.
Default

Value of name

UpdatableTrue
@@ -101,9 +99,9 @@ must have matching routing keys.
-The hostname or IP address of the local listener. Clients -at this site use the listener host and port to -establish connections to the remote service. +The hostname or IP address of the local listener. Clients at this +site use the listener host and port to establish connections to the +remote service.
Default

Value of name

UpdatableTrue
diff --git a/input/commands/listener/generate.md b/input/commands/listener/generate.md index 0d19a790..cdc2cdcb 100644 --- a/input/commands/listener/generate.md +++ b/input/commands/listener/generate.md @@ -67,9 +67,8 @@ The name of the resource to be generated.
-The port of the local listener. Clients at this site use -the listener host and port to establish connections to -the remote service. +The port of the local listener. Clients at this site use the listener +host and port to establish connections to the remote service.
UpdatableTrue
@@ -84,10 +83,9 @@ the remote service.
-The identifier used to route traffic from listeners to -connectors. To enable connecting to a service at a -remote site, the local listener and the remote connector -must have matching routing keys. +The identifier to route traffic from listeners to connectors. To +enable connecting to a service at a remote site, the local listener +and the remote connector must have matching routingKeys.
Default

Value of name

UpdatableTrue
@@ -103,9 +101,9 @@ must have matching routing keys.
-The hostname or IP address of the local listener. Clients -at this site use the listener host and port to -establish connections to the remote service. +The hostname or IP address of the local listener. Clients at this +site use the listener host and port to establish connections to the +remote service.
Default

Value of name

UpdatableTrue
diff --git a/input/commands/listener/update.md b/input/commands/listener/update.md index 047160b5..e8dd781e 100644 --- a/input/commands/listener/update.md +++ b/input/commands/listener/update.md @@ -61,9 +61,9 @@ The name of the resource to be updated.
-The hostname or IP address of the local listener. Clients -at this site use the listener host and port to -establish connections to the remote service. +The hostname or IP address of the local listener. Clients at this +site use the listener host and port to establish connections to the +remote service.
Default

Value of name

UpdatableTrue
@@ -79,9 +79,8 @@ establish connections to the remote service.
-The port of the local listener. Clients at this site use -the listener host and port to establish connections to -the remote service. +The port of the local listener. Clients at this site use the listener +host and port to establish connections to the remote service.
UpdatableTrue
@@ -96,10 +95,9 @@ the remote service.
-The identifier used to route traffic from listeners to -connectors. To enable connecting to a service at a -remote site, the local listener and the remote connector -must have matching routing keys. +The identifier to route traffic from listeners to connectors. To +enable connecting to a service at a remote site, the local listener +and the remote connector must have matching routingKeys.
Default

Value of name

UpdatableTrue
diff --git a/input/commands/site/create.md b/input/commands/site/create.md index 6643451d..8c9b3253 100644 --- a/input/commands/site/create.md +++ b/input/commands/site/create.md @@ -76,11 +76,17 @@ sites must have link access enabled.
-Configure external access for links from remote sites. +Configure external access for links from remote sites. When +set, implies a RouterAccess resource with accessType set +according to the linkAccess value. Sites and links are the basis for creating application -networks. In a simple two-site network, at least one of -the sites must have link access enabled. +networks. In a simple two-site network, at least one of the +sites must have link access enabled. Choices include: +- `none`: No linking to this site is enabled. +- `default`: Use the default link access for the current platform. For OpenShift, the default is `route`. For other Kubernetes flavors, the default is `loadbalancer`. +- `route`: Use an OpenShift route. +- `loadbalancer`: Use a Kubernetes load balancer.
Default

default

Choices
default

Use the default link access. On OpenShift, the default is route. For other Kubernetes flavors, the default is loadbalancer.

@@ -98,14 +104,18 @@ the sites must have link access enabled.
-Configure the site for high availability (HA). HA sites +Configure the site for high availability (HA). HA sites have two active routers. Note that Skupper routers are stateless, and they restart -after failure. This already provides a high level of -availability. Enabling HA goes further and reduces the +after failure. This already provides a high level of +availability. Enabling HA goes further and reduces the window of downtime caused by restarts. +By default, Pod anti-affinity will be configured on the router +Deployments when HA is enabled. To overwrite this behavior +see the `disable-anti-affinity` Site setting. +
DefaultFalse
PlatformsKubernetes
UpdatableTrue
See alsoHigh availability
diff --git a/input/commands/site/generate.md b/input/commands/site/generate.md index 0ffd031d..41f82d73 100644 --- a/input/commands/site/generate.md +++ b/input/commands/site/generate.md @@ -96,11 +96,17 @@ Select the output format.
-Configure external access for links from remote sites. +Configure external access for links from remote sites. When +set, implies a RouterAccess resource with accessType set +according to the linkAccess value. Sites and links are the basis for creating application -networks. In a simple two-site network, at least one of -the sites must have link access enabled. +networks. In a simple two-site network, at least one of the +sites must have link access enabled. Choices include: +- `none`: No linking to this site is enabled. +- `default`: Use the default link access for the current platform. For OpenShift, the default is `route`. For other Kubernetes flavors, the default is `loadbalancer`. +- `route`: Use an OpenShift route. +- `loadbalancer`: Use a Kubernetes load balancer.
Default

default

Choices
default

Use the default link access. On OpenShift, the default is route. For other Kubernetes flavors, the default is loadbalancer.

@@ -118,14 +124,18 @@ the sites must have link access enabled.
-Configure the site for high availability (HA). HA sites +Configure the site for high availability (HA). HA sites have two active routers. Note that Skupper routers are stateless, and they restart -after failure. This already provides a high level of -availability. Enabling HA goes further and reduces the +after failure. This already provides a high level of +availability. Enabling HA goes further and reduces the window of downtime caused by restarts. +By default, Pod anti-affinity will be configured on the router +Deployments when HA is enabled. To overwrite this behavior +see the `disable-anti-affinity` Site setting. +
DefaultFalse
PlatformsKubernetes
UpdatableTrue
See alsoHigh availability
diff --git a/input/commands/site/update.md b/input/commands/site/update.md index d2adbe99..280284fd 100644 --- a/input/commands/site/update.md +++ b/input/commands/site/update.md @@ -78,11 +78,17 @@ sites must have link access enabled.
-Configure external access for links from remote sites. +Configure external access for links from remote sites. When +set, implies a RouterAccess resource with accessType set +according to the linkAccess value. Sites and links are the basis for creating application -networks. In a simple two-site network, at least one of -the sites must have link access enabled. +networks. In a simple two-site network, at least one of the +sites must have link access enabled. Choices include: +- `none`: No linking to this site is enabled. +- `default`: Use the default link access for the current platform. For OpenShift, the default is `route`. For other Kubernetes flavors, the default is `loadbalancer`. +- `route`: Use an OpenShift route. +- `loadbalancer`: Use a Kubernetes load balancer.
Default

default

Choices - +
default

Use the default link access. On OpenShift, the default is route. For other Kubernetes flavors, the default is loadbalancer.

@@ -100,14 +106,18 @@ the sites must have link access enabled.
-Configure the site for high availability (HA). HA sites +Configure the site for high availability (HA). HA sites have two active routers. Note that Skupper routers are stateless, and they restart -after failure. This already provides a high level of -availability. Enabling HA goes further and reduces the +after failure. This already provides a high level of +availability. Enabling HA goes further and reduces the window of downtime caused by restarts. +By default, Pod anti-affinity will be configured on the router +Deployments when HA is enabled. To overwrite this behavior +see the `disable-anti-affinity` Site setting. +
DefaultFalse
PlatformsKubernetes
UpdatableTrue
See alsoHigh availability
diff --git a/input/commands/token/issue.md b/input/commands/token/issue.md index 90cac746..0fc68b65 100644 --- a/input/commands/token/issue.md +++ b/input/commands/token/issue.md @@ -95,8 +95,8 @@ period of time.
-The period of time in which an access token for this -grant can be redeemed. +The period of time in which an access token for this grant can be redeemed. +The default value is `15m`.
Default

15m

PlatformsKubernetes, Docker, Podman, Linux
@@ -111,8 +111,8 @@ grant can be redeemed.
-The number of times an access token for this grant can -be redeemed. +The maximum number of times an access token for this grant can be redeemed. +The default value is `1`.
Default1
PlatformsKubernetes, Docker, Podman, Linux
diff --git a/input/resources/access-grant.md b/input/resources/access-grant.md index 61448901..11504c7d 100644 --- a/input/resources/access-grant.md +++ b/input/resources/access-grant.md @@ -14,14 +14,12 @@ refdog_object_has_attributes: true # AccessGrant resource -Permission to redeem access tokens for links to the local -site. A remote site can use a token containing the grant -URL and secret code to obtain a certificate signed by the -grant's certificate authority (CA), within a certain -expiration window and for a limited number of redemptions. +Permission to redeem access tokens for links to the local site. +A remote site can use a token containing the grant URL and secret +code to obtain a certificate signed by the grant's certificate authority (CA), +within a certain expiration window and for a limited number of redemptions. -The `code`, `url`, and `ca` properties of the resource -status are used to generate access tokens from the grant. +The code, url, and ca properties of the resource status are used to generate access tokens from the grant. ## Metadata properties @@ -63,8 +61,8 @@ The namespace of the resource.
-The number of times an access token for this grant can -be redeemed. +The maximum number of times an access token for this grant can be redeemed. +The default value is `1`.
Default1
@@ -78,8 +76,8 @@ be redeemed.
-The period of time in which an access token for this -grant can be redeemed. +The period of time in which an access token for this grant can be redeemed. +The default value is `15m`.
Default

15m

@@ -95,11 +93,8 @@ grant can be redeemed.
-The secret code to use to authenticate access tokens submitted -for redemption. - -If not set, a value is generated and placed in the `code` -status property. +Advanced. The secret code to use to authenticate access tokens submitted for redemption. +If not set, a value is generated and placed in the code status property. @@ -114,10 +109,8 @@ status property.
-The name of a Kubernetes secret used to generate a -certificate when redeeming a token for this grant. - -If not set, `defaultIssuer` on the Site rsource is used. +Advanced. The name of a Kubernetes secret used to generate a certificate when redeeming a token for this grant. +If not set, `defaultIssuer` on the Site resource is used.
See alsoRouter TLS, Kubernetes TLS secrets
@@ -153,10 +146,8 @@ their default values.
The current state of the resource. - - `Pending`: The resource is being processed. -- `Error`: There was an error processing the resource. See - `message` for more information. +- `Error`: There was an error processing the resource. See `message` for more information. - `Ready`: The resource is ready to use.
See alsoResource status
@@ -171,8 +162,7 @@ The current state of the resource.
-A human-readable status message. Error messages are reported -here. +A human-readable status message. Error messages are reported here.
See alsoResource status
@@ -186,8 +176,7 @@ here.
-The number of times a token for this grant has been -redeemed. +The number of times a token for this grant has been redeemed. @@ -229,8 +218,7 @@ The URL of the token-redemption service for this grant.
-The trusted server certificate of the token-redemption -service for this grant. +The trusted server certificate of the token-redemption service for this grant. @@ -244,8 +232,7 @@ service for this grant.
-The secret code used to authenticate access tokens -submitted for redemption. +The secret code used to authenticate access tokens submitted for redemption.
Default

Generated

@@ -261,15 +248,11 @@ submitted for redemption.
-A set of named conditions describing the current state of the -resource. - +A set of named conditions describing the current state of the resource. - `Processed`: The controller has accepted the grant. -- `Resolved`: The grant service is available to process tokens - for this grant. -- `Ready`: The grant is ready to use. All other - conditions are true. +- `Resolved`: The grant service is available to process tokens for this grant. +- `Ready`: The grant is ready to use. All other conditions are true.
See alsoResource status, Kubernetes conditions
diff --git a/input/resources/access-token.md b/input/resources/access-token.md index 9e33b504..57b6bdef 100644 --- a/input/resources/access-token.md +++ b/input/resources/access-token.md @@ -18,14 +18,9 @@ refdog_object_has_attributes: true # AccessToken resource -A short-lived credential used to create a link. An access token -contains the URL and secret code of a corresponding access grant. - -**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 +A short-lived credential used to create a link between sites. +An access token contains the URL and secret code of a corresponding access grant. +**Note:** Access tokens are typically issued and redeemed using the Skupper CLI. ## Metadata properties @@ -83,8 +78,7 @@ The URL of the grant service at the remote site.
-The secret code used to authenticate the token when -submitted for redemption. +The secret code used to authenticate the token when submitted for redemption. @@ -98,8 +92,7 @@ submitted for redemption.
-The trusted server certificate of the grant service at the -remote site. +The trusted server certificate of the grant service at the remote site. @@ -148,8 +141,7 @@ their default values.
-True if the token has been redeemed. Once a token is -redeemed, it cannot be used again. +True if the token has been redeemed. Once a token is redeemed, it cannot be used again.
DefaultFalse
@@ -198,9 +190,7 @@ here.
-A set of named conditions describing the current state of the -resource. - +A set of named conditions describing the current state of the resource. - `Redeemed`: The token has been exchanged for a link. diff --git a/input/resources/attached-connector-binding.md b/input/resources/attached-connector-binding.md index 87e5cfe6..c8580865 100644 --- a/input/resources/attached-connector-binding.md +++ b/input/resources/attached-connector-binding.md @@ -10,7 +10,10 @@ refdog_object_has_attributes: true # AttachedConnectorBinding resource -A binding to an attached connector in a peer namespace. +An attached connector binding is a binding to an attached connector in a peer namespace that allows you to +bring a workload into your existing VAN without creating a separate site or establishing inter-site links. +The name of this resource must be the same as that of the associated AttachedConnector resource in the peer +namespace. ## Metadata properties @@ -57,8 +60,7 @@ The namespace of the resource.
-The name of the namespace where the associated -AttachedConnector is located. +The name of the namespace where the associated AttachedConnector is located. diff --git a/input/resources/attached-connector.md b/input/resources/attached-connector.md index 71c1afc2..c45e2351 100644 --- a/input/resources/attached-connector.md +++ b/input/resources/attached-connector.md @@ -10,7 +10,8 @@ refdog_object_has_attributes: true # AttachedConnector resource -A connector in a peer namespace. +An attached connector is a connector in a peer namespace that allows you to bring a workload into your existing VAN without creating a separate site or establishing inter-site links. +The name of this resource must be the same as that of the associated AttachedConnectorBinding resource in the site namespace. ## Metadata properties @@ -57,8 +58,7 @@ The namespace of the resource.
-The name of the namespace in which the site this connector -should be attached to is defined. +The name of the namespace in which the site this connector should be attached to is defined. diff --git a/input/resources/connector.md b/input/resources/connector.md index ca516f57..ee5f5fa5 100644 --- a/input/resources/connector.md +++ b/input/resources/connector.md @@ -14,16 +14,14 @@ refdog_object_has_attributes: true # Connector resource -A connector binds a local workload to [listeners](listener.html) in -remote [sites](site.html). Listeners and connectors are matched by -routing key. +A connector binds a local workload to listeners in remote sites. Listeners +and connectors are matched by routing key. -On Kubernetes, a Connector resource 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 resource 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 @@ -82,10 +80,9 @@ The namespace of the resource.
-The identifier used to route traffic from listeners to -connectors. To expose a local workload to a remote site, the -remote listener and the local connector must have matching -routing keys. +The identifier used to route traffic from listeners to connectors. +To expose a local workload to a remote site, the remote listener and +the local connector must have matching routing keys.
UpdatableTrue
See alsoRouting key concept
@@ -115,10 +112,10 @@ The port on the target server to connect to.
-A Kubernetes label selector for specifying target server pods. It -uses `=` syntax. +A Kubernetes label selector for specifying target server pods. It uses += syntax. -On Kubernetes, either `selector` or `host` is required. +On Kubernetes, either selector or host is required.
UpdatableTrue
See alsoKubernetes label selectors
@@ -133,12 +130,12 @@ On Kubernetes, either `selector` or `host` is required.
-The hostname or IP address of the server. This is an -alternative to `selector` for specifying the target server. +The hostname or IP address of the server. This is an alternative to +selector for specifying the target server. -On Kubernetes, either `selector` or `host` is required. +On Kubernetes, either selector or host is required. -On Docker, Podman, or Linux, `host` is required. +On Docker, Podman, or Linux, host is required.
UpdatableTrue
@@ -147,84 +144,83 @@ On Docker, Podman, or Linux, `host` is required. @@ -237,11 +233,10 @@ matches the hostname in the server's certificate.
-A map containing additional settings. Each map entry has a -string name and a string value. +A map containing additional settings. Each map entry has a string name and a +string value. -**Note:** In general, we recommend not changing settings from -their default values. +Note: In general, we recommend not changing settings from their default values.
See alsoResource settings
diff --git a/input/resources/index.md b/input/resources/index.md index ada72e88..45bffc83 100644 --- a/input/resources/index.md +++ b/input/resources/index.md @@ -26,7 +26,7 @@ refdog_links:
SiteA site is a place on the network where application workloads are running
LinkA link is a channel for communication between sites
AccessGrantPermission to redeem access tokens for links to the local site
AccessTokenA short-lived credential used to create a link
AccessTokenA short-lived credential used to create a link between sites
RouterAccessConfiguration for secure access to the site router
@@ -35,8 +35,8 @@ refdog_links: - - + +
ListenerA listener binds a local connection endpoint to connectors in remote sites
ConnectorA connector binds a local workload to listeners in remote sites
AttachedConnectorA connector in a peer namespace
AttachedConnectorBindingA binding to an attached connector in a peer namespace
AttachedConnectorAn attached connector is a connector in a peer namespace that allows you to bring a workload into your existing VAN without creating a separate site or establishing inter-site links
AttachedConnectorBindingAn attached connector binding is a binding to an attached connector in a peer namespace that allows you to bring a workload into your existing VAN without creating a separate site or establishing inter-site links
diff --git a/input/resources/link.md b/input/resources/link.md index 5ee49da5..db26dbfe 100644 --- a/input/resources/link.md +++ b/input/resources/link.md @@ -14,7 +14,7 @@ refdog_object_has_attributes: true # Link resource -A link is a channel for communication between [sites](site.html). +A link is a channel for communication between sites. Links carry application connections and requests. A set of linked sites constitutes a network. @@ -25,9 +25,7 @@ _link access_. Link access provides an external access point for accepting links. **Note:** Links are not usually created directly. Instead, you can -use an [access token][token] to obtain a link. - -[token]: access-token.html +use an AccessToken to obtain a link. ## Metadata properties @@ -85,8 +83,7 @@ port, and group.
-The configured routing cost of sending traffic over -the link. +The configured routing cost of sending traffic over the link.
Default1
See alsoLoad balancing
@@ -145,10 +142,8 @@ their default values.
The current state of the resource. - - `Pending`: The resource is being processed. -- `Error`: There was an error processing the resource. See - `message` for more information. +- `Error`: There was an error processing the resource. See `message` for more information. - `Ready`: The resource is ready to use.
See alsoResource status
@@ -163,8 +158,7 @@ The current state of the resource.
-A human-readable status message. Error messages are reported -here. +A human-readable status message. Error messages are reported here.
See alsoResource status
@@ -207,15 +201,11 @@ The name of the site linked to.
-A set of named conditions describing the current state of the -resource. - +A set of named conditions describing the current state of the resource. -- `Configured`: The link configuration has been applied to - the router. +- `Configured`: The link configuration has been applied to the router. - `Operational`: The link to the remote site is active. -- `Ready`: The link is ready to use. All other conditions - are true. +- `Ready`: The link is ready for use. All other conditions are true.
See alsoResource status, Kubernetes conditions
diff --git a/input/resources/listener.md b/input/resources/listener.md index 0028ad0f..40882eee 100644 --- a/input/resources/listener.md +++ b/input/resources/listener.md @@ -14,13 +14,12 @@ refdog_object_has_attributes: true # Listener resource -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 binds a local connection endpoint to connectors in remote sites. +Listeners and connector are matched by routing key. -A Listener resource specifies 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 specifies a host and port for accepting connections +from local client. To expose a multi-port service, create multiple listeners +with the same host value. ## Examples @@ -80,10 +79,9 @@ The namespace of the resource.
-The identifier used to route traffic from listeners to -connectors. To enable connecting to a service at a -remote site, the local listener and the remote connector -must have matching routing keys. +The identifier to route traffic from listeners to connectors. To +enable connecting to a service at a remote site, the local listener +and the remote connector must have matching routingKeys.
UpdatableTrue
See alsoRouting key concept
@@ -98,9 +96,9 @@ must have matching routing keys.
-The hostname or IP address of the local listener. Clients -at this site use the listener host and port to -establish connections to the remote service. +The hostname or IP address of the local listener. Clients at this +site use the listener host and port to establish connections to the +remote service.
UpdatableTrue
@@ -115,9 +113,8 @@ establish connections to the remote service.
-The port of the local listener. Clients at this site use -the listener host and port to establish connections to -the remote service. +The port of the local listener. Clients at this site use the listener +host and port to establish connections to the remote service.
UpdatableTrue
@@ -132,7 +129,9 @@ the remote service.
-If true, expose each pod as an individual service. +If true, expose each pod as an individual service. This allows individual +pods to be directly connected across a network. The pod names will be used +to create each service.
DefaultFalse
See alsoIndividual pod services
@@ -147,15 +146,14 @@ If true, expose each pod as an individual service.
-The name of a bundle of TLS certificates used for secure -client-to-router communication. The bundle contains the -server certificate and key. It optionally includes the -trusted client certificate (usually a CA) for mutual TLS. +The name of a bundle of TLS certificates used for secure client-to-router +communication. The bundle contains the server certificate and key. It +optionally includes the trusted client certificate (usually a CA) for +mutual TLS. -On Kubernetes, the value is the name of a Secret in the -current namespace. On Docker, Podman, and Linux, the value is -the name of a directory under `input/certs/` in the current -namespace. +On Kubernetes, the value is the name of a Secret in the current namespace. +On Docker, Podman, and Linux, the value is the name of a directory under +input/certs/ in the current namespace.
See alsoApplication TLS, Kubernetes TLS secrets, System TLS credentials
@@ -170,17 +168,11 @@ namespace.
-A map containing additional settings. Each map entry has a -string name and a string value. +A map containing additional settings. Each map entry has a string name and a string value. **Note:** In general, we recommend not changing settings from their default values. - -- `observer`: Set the protocol observer used to generate - traffic metrics.
- Default: `auto`. Choices: `auto`, `none`, `http1`, `http2`. -
See alsoResource settings
@@ -196,10 +188,8 @@ their default values.
The current state of the resource. - - `Pending`: The resource is being processed. -- `Error`: There was an error processing the resource. See - `message` for more information. +- `Error`: There was an error processing the resource. See `message` for more information. - `Ready`: The resource is ready to use.
See alsoResource status
@@ -214,8 +204,7 @@ The current state of the resource.
-A human-readable status message. Error messages are reported -here. +A human-readable status message. Error messages are reported here.
See alsoResource status
@@ -229,8 +218,7 @@ here.
-True if there is at least one connector with a matching -routing key (usually in a remote site). +True if there is at least one connector with a matching routing key (usually in a remote site).
DefaultFalse
See alsoRouting key concept
@@ -245,16 +233,11 @@ routing key (usually in a remote site).
-A set of named conditions describing the current state of the -resource. - +A set of named conditions describing the current state of the resource. -- `Configured`: The listener configuration has been applied - to the router. -- `Matched`: There is at least one connector corresponding to - this listener. -- `Ready`: The listener is ready to use. All other conditions - are true. +- `Configured`: The listener configuration has been applied to the router. +- `Operational`: There is at least one connector corresponding to this listener. +- `Ready`: The listener is ready for use. All other conditions are true.
See alsoResource status, Kubernetes conditions
diff --git a/input/resources/router-access.md b/input/resources/router-access.md index c31e5b94..3779f432 100644 --- a/input/resources/router-access.md +++ b/input/resources/router-access.md @@ -97,6 +97,10 @@ directory under `input/certs/` in the current namespace.
+When set, Skupper generates the TLS credentials to be +stored in the Secret specified by `tlsCredentials`. See +also `issuer`. +
DefaultFalse
@@ -109,6 +113,10 @@ directory under `input/certs/` in the current namespace.
+The name of the Kubernetes Secret containing the signing CA +used to generate TLS certificates for the RouterAccess when +`generateTlsCredentials` is set. +
@@ -121,6 +129,15 @@ directory under `input/certs/` in the current namespace.
+Configures the access type for the router endpoints. +Available access types and the default selection is +configured on the Skupper controller for Kubernetes. + +The options available by default are: + - `local`: No external ingress. Implies a Kubernetes Service with type CluterIP. + - `route`: Exposed via an OpenShift Route. + - `loadbalancer`: Exposed via a Kubernetes Service with type LoadBalancer. +
Default

On OpenShift, the default is route. For other Kubernetes flavors, the default is loadbalancer.

Choices
route

Use an OpenShift route. OpenShift only.

@@ -191,11 +208,9 @@ their default values.
The current state of the resource. - -- `Pending`: The resource is being processed. -- `Error`: There was an error processing the resource. See - `message` for more information. -- `Ready`: The resource is ready to use. + - `Pending`: The resource is being processed. + - `Error`: There was an error processing the resource. See `message` for more information. + - `Ready`: The resource is ready to use.
See alsoResource status
@@ -209,8 +224,7 @@ The current state of the resource.
-A human-readable status message. Error messages are reported -here. +A human-readable status message. Error messages are reported here.
See alsoResource status
@@ -225,15 +239,11 @@ here.
-A set of named conditions describing the current state of the -resource. - +A set of named conditions describing the current state of the resource. -- `Configured`: The router access configuration has been applied to - the router. -- `Resolved`: The connection endpoints are available. -- `Ready`: The router access is ready to use. All other - conditions are true. + - `Configured`: The output resources for this resource have been created. + - `Resolved`: The connection endpoints are available. + - `Ready`: The router access is ready for use. All other conditions are true.
See alsoResource status, Kubernetes conditions
diff --git a/input/resources/site.md b/input/resources/site.md index 807a1220..ceb29262 100644 --- a/input/resources/site.md +++ b/input/resources/site.md @@ -15,10 +15,10 @@ refdog_object_has_attributes: true # Site resource A site is a place on the network where application workloads are -running. Sites are joined by [links](link.html). +running. Sites are joined by links. -The Site resource is the basis for site configuration. It is the -parent of all Skupper resources in its namespace. There can be only +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 @@ -86,11 +86,17 @@ The namespace of the resource.
-Configure external access for links from remote sites. +Configure external access for links from remote sites. When +set, implies a RouterAccess resource with accessType set +according to the linkAccess value. Sites and links are the basis for creating application -networks. In a simple two-site network, at least one of -the sites must have link access enabled. +networks. In a simple two-site network, at least one of the +sites must have link access enabled. Choices include: +- `none`: No linking to this site is enabled. +- `default`: Use the default link access for the current platform. For OpenShift, the default is `route`. For other Kubernetes flavors, the default is `loadbalancer`. +- `route`: Use an OpenShift route. +- `loadbalancer`: Use a Kubernetes load balancer.
Default

none

Choices
none

No linking to this site is permitted.

@@ -109,14 +115,18 @@ the sites must have link access enabled.
-Configure the site for high availability (HA). HA sites +Configure the site for high availability (HA). HA sites have two active routers. Note that Skupper routers are stateless, and they restart -after failure. This already provides a high level of -availability. Enabling HA goes further and reduces the +after failure. This already provides a high level of +availability. Enabling HA goes further and reduces the window of downtime caused by restarts. +By default, Pod anti-affinity will be configured on the router +Deployments when HA is enabled. To overwrite this behavior +see the `disable-anti-affinity` Site setting. +
DefaultFalse
UpdatableTrue
See alsoHigh availability
@@ -130,12 +140,12 @@ window of downtime caused by restarts.
-The name of a Kubernetes secret containing the signing CA -used to generate a certificate from a token. A secret is -generated if none is specified. +Advanced. The name of a Kubernetes secret containing the +signing CA used to generate a certificate from a token. A +secret is generated if none is specified. This issuer is used by AccessGrant and RouterAccess if a -specific issuer is not set. +specific issuer is not set. Defaults to `skupper-site-ca`
Default

skupper-site-ca

UpdatableTrue
See alsoRouter TLS, Kubernetes TLS secrets
@@ -151,19 +161,15 @@ specific issuer is not set.
-Configure the site to operate in edge mode. Edge sites -cannot accept links from remote sites. +Advanced. Configure the site to operate in edge mode. Edge +sites cannot accept links from remote sites. Edge mode can help you scale your network to large numbers -of sites. However, for networks with 16 or fewer sites, +of sites. However, for networks with 16 or fewer sites, there is little benefit. Currently, edge sites cannot also have HA enabled. - -
DefaultFalse
See alsoLarge networks
@@ -177,9 +183,9 @@ router infrastructure. -->
-The name of the Kubernetes service account under which to run -the Skupper router. A service account is generated if none is -specified. +Advanced. The name of the Kubernetes service account under +which to run the Skupper router. A service account is +generated if none is specified.
Default

Generated

See alsoKubernetes service accounts
@@ -195,20 +201,17 @@ specified.
-A map containing additional settings. Each map entry has a -string name and a string value. +Advanced. A map containing additional settings. Each map +entry has a string name and a string value. -**Note:** In general, we recommend not changing settings from -their default values. +**Note:** In general, we recommend not changing `settings` +from their default values. - -- `routerDataConnections`: Set the number of data - connections the router uses when linking to other - routers.
- Default: *Computed based on the number of router worker - threads. Minimum 2.* -- `routerLogging`: Set the router logging level.
- Default: `info`. Choices: `info`, `warning`, `error`. +- `routerDataConnections`: Set the number of router worker threads. Minimum 2. +- `routerLogging`: Set the number of router logging level. Options are "info", "warning", "error". +- `disable-anti-affinity`: Set to "true" in order to prevent skupper from specifying router pod affinity. +- `size`: The desired site sizing profile to use for constraining pod resources. Corresponds to a ConfigMap with matching `skupper.io/site-sizing` label. +- `tls-prior-valid-revisions`: Set the number of revisions to TLS Secrets backing Site Link connections that are permissible to hold open to preserve established service connections. An unsigned integer defaults to 1. Set to 0 to immediately disrupt connections secured with old TLS configurations.
See alsoResource settings
@@ -225,10 +228,8 @@ their default values.
The current state of the resource. - - `Pending`: The resource is being processed. -- `Error`: There was an error processing the resource. See - `message` for more information. +- `Error`: There was an error processing the resource. See `message` for more information. - `Ready`: The resource is ready to use.
See alsoResource status
@@ -243,8 +244,7 @@ The current state of the resource.
-A human-readable status message. Error messages are reported -here. +A human-readable status message. Error messages are reported here.
See alsoResource status
@@ -259,17 +259,12 @@ here.
-A set of named conditions describing the current state of the -resource. +A set of named conditions describing the current state of the resource. - -- `Configured`: The output resources for this resource have - been created. +- `Configured`: The output resources for this resource have been created. - `Running`: There is at least one router pod running. -- `Resolved`: The hostname or IP address for link access is - available. -- `Ready`: The site is ready for use. All other conditions - are true. +- `Resolved`: The hostname or IP address for link access is available. +- `Ready`: The site is ready for use. All other conditions are true.
See alsoResource status, Kubernetes conditions
@@ -284,8 +279,7 @@ resource.
-The name of the Kubernetes secret containing the active -default signing CA. +The name of the Kubernetes secret containing the active default signing CA.
See alsoRouter TLS, Kubernetes TLS secrets
@@ -300,10 +294,7 @@ default signing CA.
-An array of connection endpoints. Each item has a name, host, -port, and group. - -These include connection endpoints for link access. +An array of connection endpoints. Each item has a name, host, port, and group. These include connection endpoints for link access.
See alsoLink concept, Site linking
diff --git a/sync.py b/sync.py new file mode 100644 index 00000000..3187df0c --- /dev/null +++ b/sync.py @@ -0,0 +1,280 @@ +#!/usr/bin/env python3 +""" +sync_yaml_descriptions.py + +Sync all CRD openAPIV3Schema descriptions into a documentation-style site.yaml. + +Features +- Requires ruamel.yaml (round-trip). No fallbacks. +- Auto-detects target style: + 1) JSON Schema (mapping-based properties) → path-to-path sync + 2) Catalog style (properties is a list of {name: ...}) → name-based sync +- Copies CRD root schema description to: + - target schema root (if present) + - top-level document 'description' (if present) +- Only updates 'description' fields. + +Usage + ./sync_yaml_descriptions.py --from skupper_site_crd.yaml --to site.yaml --in-place --report +""" + +import sys, argparse +from typing import Any, Dict, List, Tuple, Optional + +from ruamel.yaml import YAML +from ruamel.yaml.comments import CommentedMap, CommentedSeq + +Json = Any +PathT = Tuple[str, ...] + + +# ------------- YAML IO ------------- + +def load_yaml_stream(path: Optional[str]) -> List[Json]: + y = YAML(typ="rt") + y.preserve_quotes = True + with (open(path, "r", encoding="utf-8") if path else sys.stdin) as fh: + return [doc for doc in y.load_all(fh) if doc is not None] + +def dump_yaml_stream(docs: List[Json], path: Optional[str]) -> None: + y = YAML(typ="rt") + y.preserve_quotes = True + y.indent(mapping=2, sequence=4, offset=2) + with (open(path, "w", encoding="utf-8") if path else sys.stdout) as fh: + y.dump_all(docs, fh) + + +# ------------- helpers ------------- + +def is_map(x: Json) -> bool: + return isinstance(x, (dict, CommentedMap)) + +def is_seq(x: Json) -> bool: + return isinstance(x, (list, CommentedSeq)) + +def set_block_style_if_multiline(node_parent: Json, key: str) -> None: + try: + val = node_parent[key] + if isinstance(val, str) and "\n" in val: + node_parent[key].fa.set_block_style() # type: ignore[attr-defined] + except Exception: + pass + + +# ------------- CRD extraction ------------- + +def find_crd_schema(doc: Json) -> Optional[Json]: + try: + spec = doc.get("spec") if is_map(doc) else None + versions = spec.get("versions", []) if is_map(spec) else [] + for v in versions or []: + schema = (v.get("schema") or {}).get("openAPIV3Schema") if is_map(v) else None + if is_map(schema): + return schema + except Exception: + pass + return None + +def walk_schema(node: Json, path: PathT = ()) -> List[Tuple[PathT, Dict[str, Any]]]: + out: List[Tuple[PathT, Dict[str, Any]]] = [] + if not is_map(node): + return out + out.append((path, node)) + props = node.get("properties") + if is_map(props): + for key, sub in props.items(): + out.extend(walk_schema(sub, path + (str(key),))) + if "items" in node: + out.extend(walk_schema(node.get("items"), path + ("items",))) + if "additionalProperties" in node: + ap = node.get("additionalProperties") + if is_map(ap): + out.extend(walk_schema(ap, path + ("additionalProperties",))) + elif is_seq(ap): + for i, sub in enumerate(ap): + out.extend(walk_schema(sub, path + ("additionalProperties", str(i)))) + for kw in ("allOf", "anyOf", "oneOf"): + seq = node.get(kw) + if is_seq(seq): + for i, sub in enumerate(seq): + out.extend(walk_schema(sub, path + (kw, str(i)))) + return out + +def build_desc_map(schema: Json) -> Dict[PathT, str]: + out: Dict[PathT, str] = {} + for p, n in walk_schema(schema): + d = n.get("description") if is_map(n) else None + if isinstance(d, str): + out[p] = d + return out + + +# ------------- Target detection ------------- + +def looks_like_json_schema_root(node: Json) -> bool: + return is_map(node) and ("properties" in node or "type" in node or "items" in node) + +def find_first_schema_like(node: Json) -> Optional[Json]: + if looks_like_json_schema_root(node) and ("properties" in node or "type" in node): + return node + if is_map(node): + for _, v in node.items(): + r = find_first_schema_like(v) + if r is not None: + return r + if is_seq(node): + for v in node: + r = find_first_schema_like(v) + if r is not None: + return r + return None + +def is_catalog_properties_block(block: Json) -> bool: + # In site.yaml, e.g.: spec: { properties: [ {name: linkAccess, description: ...}, ... ] } + return is_map(block) and is_seq(block.get("properties")) + +def find_catalog_sections(doc: Json) -> Dict[str, Json]: + # return mapping of section name -> section mapping (with 'properties' list) + sections = {} + for key in ("spec", "status", "metadata"): + sec = doc.get(key) + if is_map(sec) and is_seq(sec.get("properties")): + sections[key] = sec + return sections + + +# ------------- Apply updates ------------- + +def apply_to_json_schema(dst_schema: Json, src_descs: Dict[PathT, str], report: bool) -> Tuple[int,int]: + index: Dict[PathT, Dict[str, Any]] = dict(walk_schema(dst_schema)) + updated = 0 + skipped = 0 + for p, d in src_descs.items(): + node = index.get(p) + if node is None: + skipped += 1 + if report: + print(f"[miss] {'/'.join(p) or ''}", file=sys.stderr) + continue + if node.get("description") != d: + node["description"] = d + set_block_style_if_multiline(node, "description") + updated += 1 + if report: + print(f"[update] {'/'.join(p) or ''}", file=sys.stderr) + return updated, skipped + +def apply_to_catalog(dst_doc: Json, src_descs: Dict[PathT, str], report: bool) -> Tuple[int,int]: + """ + Map CRD paths like ('spec','linkAccess') or ('status','conditions') to + catalog entries like dst_doc['spec']['properties'][i]['name']=='linkAccess'. + """ + sections = find_catalog_sections(dst_doc) + updated = 0 + skipped = 0 + + # Build a quick index: for each section, name -> item mapping + name_index: Dict[str, Dict[str, Json]] = {} + for sec_name, sec in sections.items(): + idx: Dict[str, Json] = {} + for item in sec.get("properties") or []: + if is_map(item) and isinstance(item.get("name"), str): + idx[item["name"]] = item + name_index[sec_name] = idx + + for p, d in src_descs.items(): + # We only attempt simple
/ matches + if len(p) != 2: + continue + section, field = p + if section not in name_index: + continue + target = name_index[section].get(field) + if target is None: + skipped += 1 + if report: + print(f"[miss] {section}/{field}", file=sys.stderr) + continue + if target.get("description") != d: + target["description"] = d + set_block_style_if_multiline(target, "description") + updated += 1 + if report: + print(f"[update] {section}/{field}", file=sys.stderr) + + return updated, skipped + + +# ------------- Main ------------- + +def main(): + ap = argparse.ArgumentParser(description="Sync CRD descriptions into site.yaml (schema or catalog style).") + ap.add_argument("--from", dest="src", required=True, help="CRD YAML path") + ap.add_argument("--to", dest="dst", default=None, help="Target YAML path (site). If omitted, read from stdin and write to stdout.") + ap.add_argument("--in-place", action="store_true", help="Overwrite target file (requires --to)") + ap.add_argument("--report", action="store_true", help="Report updates/misses to stderr") + args = ap.parse_args() + + src_docs = load_yaml_stream(args.src) + if not src_docs: + print("[sync] ERROR: source YAML is empty", file=sys.stderr); sys.exit(2) + dst_docs = load_yaml_stream(args.dst) + if not dst_docs: + print("[sync] ERROR: target YAML is empty", file=sys.stderr); sys.exit(2) + + src_doc = src_docs[0] + dst_doc = dst_docs[0] + + src_schema = find_crd_schema(src_doc) + if not is_map(src_schema): + print("[sync] ERROR: could not find openAPIV3Schema in source", file=sys.stderr); sys.exit(2) + src_descs = build_desc_map(src_schema) + + # Decide target mode + dst_schema_like = find_first_schema_like(dst_doc) + catalog_sections = find_catalog_sections(dst_doc) + + total_updated = 0 + total_skipped = 0 + + if dst_schema_like and "properties" in dst_schema_like and is_map(dst_schema_like.get("properties")): + # JSON Schema mode + u, s = apply_to_json_schema(dst_schema_like, src_descs, report=args.report) + total_updated += u; total_skipped += s + + if catalog_sections: + # Catalog mode (this will handle your 'linkAccess' case) + u, s = apply_to_catalog(dst_doc, src_descs, report=args.report) + total_updated += u; total_skipped += s + + if not dst_schema_like and not catalog_sections: + print("[sync] ERROR: target doc does not look like schema or catalog; nothing to update", file=sys.stderr) + sys.exit(2) + + # Sync root description to schema root and to top-level doc description (if present) + root_desc = src_schema.get("description") + root_updates = 0 + if isinstance(root_desc, str): + if dst_schema_like is not None and dst_schema_like.get("description") != root_desc: + dst_schema_like["description"] = root_desc + set_block_style_if_multiline(dst_schema_like, "description") + root_updates += 1 + if args.report: print("[update] ", file=sys.stderr) + if "description" in dst_doc and dst_doc.get("description") != root_desc: + dst_doc["description"] = root_desc + set_block_style_if_multiline(dst_doc, "description") + root_updates += 1 + if args.report: print("[update] ", file=sys.stderr) + + print(f"[sync] updated {total_updated} (+{root_updates} root), skipped {total_skipped}", file=sys.stderr) + + if args.in_place: + if not args.dst: + print("[sync] ERROR: --in-place requires --to FILE", file=sys.stderr); sys.exit(2) + dump_yaml_stream(dst_docs, args.dst) + else: + dump_yaml_stream(dst_docs, None) + + +if __name__ == "__main__": + main() diff --git a/sync.sh b/sync.sh new file mode 100644 index 00000000..062a1945 --- /dev/null +++ b/sync.sh @@ -0,0 +1,9 @@ +python sync.py --from crds/skupper_site_crd.yaml --to config/resources/site.yaml --in-place +python sync.py --from crds/skupper_router_access_crd.yaml --to config/resources/router-access.yaml --in-place +python sync.py --from crds/skupper_access_grant_crd.yaml --to config/resources/access-grant.yaml --in-place +python sync.py --from crds/skupper_access_token_crd.yaml --to config/resources/access-token.yaml --in-place +python sync.py --from crds/skupper_link_crd.yaml --to config/resources/link.yaml --in-place +python sync.py --from crds/skupper_connector_crd.yaml --to config/resources/connector.yaml --in-place +python sync.py --from crds/skupper_attached_connector_crd.yaml --to config/resources/attached-connector.yaml --in-place +python sync.py --from crds/skupper_attached_connector_binding_crd.yaml --to config/resources/attached-connector-binding.yaml --in-place +python sync.py --from crds/skupper_listener_crd.yaml --to config/resources/listener.yaml --in-place