use default named links (#558)

Signed-off-by: Etai Lev Ran <[email protected]>

website/content/en/blog/hello-world/index.md

@@ -14,7 +14,7 @@ I’m ClusterLink, and as the new kid on the block, I’d like to
  say hello and introduce myself. I’m just starting out as an open-source
  project trying to find my place in the big, wide world of multicluster
  Kubernetes connectivity. This is my first venture away from
- my [home on GitHub](https://github.com/clusterlink-net/clusterlink).
+ my [home on GitHub][].
 
 My core is centered around three key principles: **Seamlessness**, **Simplicity**,
  and **Security**. I focus on applying these principles to service access across
@@ -71,15 +71,19 @@ First things first, though – I want to make it clear that I’m "work in progr
 
 So, what do you say? Want to give me a try? I promise I won’t disappoint.
  And if you find me useful (which I’m sure you will), there are plenty of
- ways you can help me grow and improve: join the [users' mailing list](https://groups.google.com/g/clusterlink-users),
- [issues or enhancement requests](https://github.com/clusterlink-net/clusterlink/issues),
- provide additional [documentation](https://github.com/clusterlink-net/clusterlink/tree/main/website)
- and [code](https://github.com/clusterlink-net/clusterlink), or make a suggestion.
- The possibilities are endless!
+ ways you can help me grow and improve: join the [users' mailing list][],
+ [issues or enhancement requests][], provide additional [documentation][]
+ and [code][], or make a suggestion. The possibilities are endless!
 
 I can't wait to start on this journey with all of you. Together, we'll make
  the world of Kubernetes a better, safer, and more connected place.
  Happy cluster linking! 🚀
 
 [^1]: While normal access policies work, the implementation of privileged policy tier
 was ongoing and enabled shortly after the 0.1.0 release - it is currently part of `main` branch.
+
+[home on GitHub]: https://github.com/clusterlink-net/clusterlink
+[users' mailing list]: https://groups.google.com/g/clusterlink-users
+[issues or enhancement requests]: https://github.com/clusterlink-net/clusterlink/issues
+[documentation]: https://github.com/clusterlink-net/clusterlink/tree/main/website
+[code]: https://github.com/clusterlink-net/clusterlink

website/content/en/docs/main/concepts/fabric.md

@@ -4,9 +4,9 @@ description: Defining a ClusterLink fabric
 weight: 10
 ---
 
-The concept of a *Fabric* encapsulates a set of cooperating [peers][concept-peer].
- All peers in a fabric can communicate and may share [services][concept-service]
- between them, with access governed by [policies][concept-policy].
+The concept of a *Fabric* encapsulates a set of cooperating [peers][].
+ All peers in a fabric can communicate and may share [services][]
+ between them, with access governed by [policies][].
  The Fabric acts as a root of trust for peer to peer communications (i.e.,
  it functions as the certificate authority enabling mutual authentication between
  peers).
@@ -26,7 +26,7 @@ Currently, the concept of a Fabric is just that - a concept. It is not represent
 
 The following assume that you have access to the `clusterlink` CLI and one or more
  peers (i.e., clusters) where you'll deploy ClusterLink. The CLI can be downloaded
- from the ClusterLink [releases page on GitHub](https://github.com/clusterlink-net/clusterlink/releases/latest).
+ from the ClusterLink [releases page on GitHub][].
 
 ### Create a new fabric CA
 
@@ -44,10 +44,11 @@ This command will create the CA files `cert.pem` and `key.pem` in a directory na
 ## Related tasks
 
 Once a Fabric has been created and initialized, you can proceed with configuring
- [peers][concept-peer]. For a complete, end to end, use case please refer to the
- [iperf tutorial][tutorial-iperf].
-
-[concept-peer]: {{< relref "peers" >}}
-[concept-service]: {{< relref "services" >}}
-[concept-policy]: {{< relref "policies" >}}
-[tutorial-iperf]: {{< relref "../tutorials/iperf" >}}
+ [peers][]. For a complete, end to end, use case please refer to the
+ [iperf tutorial][].
+
+[peers]: {{< relref "peers" >}}
+[services]: {{< relref "services" >}}
+[policies]: {{< relref "policies" >}}
+[releases page on GitHub]: https://github.com/clusterlink-net/clusterlink/releases/latest
+[iperf tutorial]: {{< relref "../tutorials/iperf" >}}

website/content/en/docs/main/concepts/peers.md

@@ -5,11 +5,11 @@ weight: 20
 ---
 
 A *Peer* represents a location, such as a Kubernetes cluster, participating in a
- [fabric][concept-fabric]. Each peer may host one or more [services][concept-service]
+ [fabric][]. Each peer may host one or more [services][]
  it wishes to share with other peers. A peer is managed by a peer administrator,
  which is responsible for running the ClusterLink control and data planes. The
  administrator will typically deploy the ClusterLink components by configuring
- the [deployment CR][operator-cr]. They may also wish to provide
+ the [deployment CR][]. They may also wish to provide
  (often) coarse-grained access policies in accordance with high level corporate
  policies (e.g., "production peers should only communicate with other production peers").
 
@@ -24,9 +24,9 @@ Once a peer has been added to a fabric, it can communicate with any other peer
 
 The following assume that you have access to the `clusterlink` CLI and one or more
  peers (i.e., clusters) where you'll deploy ClusterLink. The CLI can be downloaded
- from the ClusterLink [releases page on GitHub](https://github.com/clusterlink-net/clusterlink/releases/latest).
- It also assumes that you have access to the [previously created][concept-fabric-new]
- fabric CA files.
+ from the ClusterLink [releases page on GitHub][].
+ It also assumes that you have access to the [previously created fabric][]
+ CA files.
 
 ## Initializing a new peer
 
@@ -130,8 +130,7 @@ After the operator is installed, you can deploy ClusterLink by applying
  Configurations affecting the entire peer, such as the list of known peers, are also maintained
  in the same namespace.
 
-Refer to the [operator documentation][operator-cli-flags] for a description
- of the ClusterLink CR fields.
+Refer to the [operator documentation][] for a description of the ClusterLink CR fields.
 
 ## Add or remove peers
 
@@ -179,13 +178,13 @@ There are two fundamental attributes in the peer CRD: the peer name and the list
  ClusterLink gateway endpoints through which the remote peer's services are available.
  Peer names are unique and must align with the Subject name present in their certificate
  during connection establishment. The name is used by importers in referencing an export
- (see [here][concept-service] for details).
+ (see [services][] for details).
 
 Gateway endpoint would typically be a implemented via a `NodePort` or `LoadBalancer`
  K8s service. A `NodePort` service would typically be used in local deployments
  (e.g., when running in kind clusters during development) and a `LoadBalancer` service
  would be used in cloud based deployments. These can be automatically configured and
- created via the [ClusterLink CR][concept-peer-deploy-via-cr].
+ created via the [ClusterLink CR][].
  The peer's status section includes a `Reachable` condition indicating whether the peer is currently reachable,
  and in case it is not reachable, the last time it was.
 
@@ -197,14 +196,15 @@ Gateway endpoint would typically be a implemented via a `NodePort` or `LoadBalan
 
 Once a peer has been created and initialized with the ClusterLink control and data
  planes as well as one or more remote peers, you can proceed with configuring
- [services][concept-service] and [policies][concept-policy].
- For a complete end to end use case, refer to the [iperf tutorial][tutorial-iperf].
-
-[concept-fabric]: {{< relref "fabric" >}}
-[concept-fabric-new]: {{< relref "fabric#create-a-new-fabric-ca" >}}
-[concept-service]: {{< relref "services" >}}
-[concept-policy]: {{< relref "policies" >}}
+ [services][] and [policies][].
+ For a complete end to end use case, refer to the [iperf tutorial][].
+
+[fabric]: {{< relref "fabric" >}}
+[previously created fabric]: {{< relref "fabric#create-a-new-fabric-ca" >}}
+[services]: {{< relref "services" >}}
+[policies]: {{< relref "policies" >}}
+[releases page on GitHub]: https://github.com/clusterlink-net/clusterlink/releases/latest
 [operator-cr]: {{< relref "../tasks/operator#deploy-cr-instance" >}}
-[operator-cli-flags]: {{< relref "../tasks/operator#commandline-flags" >}}
-[concept-peer-deploy-via-cr]: {{< relref "peers#deploy-clusterlink-via-the-operator-and-clusterlink-cr" >}}
-[tutorial-iperf]: {{< relref "../tutorials/iperf" >}}
+[operator documentation]: {{< relref "../tasks/operator#commandline-flags" >}}
+[ClusterLink CR]: {{< relref "peers#deploy-clusterlink-via-the-operator-and-clusterlink-cr" >}}
+[iperf tutorial]: {{< relref "../tutorials/iperf" >}}

website/content/en/docs/main/concepts/policies.md

@@ -6,17 +6,15 @@ weight: 40
 
 Access policies allow users and administrators fine-grained control over
  which client workloads may access which service. This is an important security
- mechanism for applying [micro-segmentation](https://en.wikipedia.org/wiki/Microsegmentation_(network_security)),
- which is a basic requirement of [zero-trust](https://en.wikipedia.org/wiki/Zero_trust_security_model)
+ mechanism for applying [micro-segmentation][], which is a basic requirement of [zero-trust][]
  systems. Another zero-trust principle, "Deny by default / Allow by exception", is also
  addressed by ClusterLink's access policies: a connection without an explicit policy allowing it,
  will be dropped. Access policies can also be used for enforcing corporate security rules,
  as well as segmenting the fabric into trust zones.
 
 ClusterLink's access policies are based on attributes that are attached to
- [peers][concept-peer], [services][concept-service] and client workloads.
- Each attribute is a key:value pair, similar to how
- [labels](https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/)
+ [peers][], [services][] and client workloads.
+ Each attribute is a key:value pair, similar to how [labels][]
  are used in Kubernetes. This approach, called ABAC (Attribute Based Access Control),
  allows referring to a set of entities in a single policy, rather than listing individual
  entity names. Using attributes is safer, more resilient to changes, and easier to
@@ -59,7 +57,7 @@ For a connection to be established, both the ClusterLink gateway on the client
 ## Prerequisites
 
 The following assumes that you have `kubectl` access to two or more clusters where ClusterLink
- has already been [deployed and configured][getting-started-user-setup].
+ has already been [deployed and configured][].
 
 ### Creating access policies
 
@@ -124,8 +122,7 @@ A `WorkloadSetOrSelector` object has two fields; exactly one of them must be spe
 
 - **WorkloadSets** (string array, optional) - an array of predefined sets of workload.
  Currently not supported.
-- **WorkloadSelector** (LabelSelector, optional) - a Kubernetes
- [label selector](https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#labelselector-v1-meta)
+- **WorkloadSelector** (LabelSelector, optional) - a [Kubernetes label selector][]
  defining a set of client workloads or a set of services, based on their
  attributes. An empty selector matches all workloads/services.
 
@@ -145,8 +142,13 @@ spec:
     - workloadSelector: {}
 ```
 
-More examples are available [here](https://github.com/clusterlink-net/clusterlink/tree/main/pkg/policyengine/examples)
+More examples are available on our repo under [policyengine/examples][].
 
-[concept-peer]: {{< relref "peers" >}}
-[concept-service]: {{< relref "services" >}}
-[getting-started-user-setup]: {{< relref "../getting-started/users#setup" >}}
+[peers]: {{< relref "peers" >}}
+[services]: {{< relref "services" >}}
+[micro-segmentation]: https://en.wikipedia.org/wiki/Microsegmentation_(network_security)
+[zero-trust]: https://en.wikipedia.org/wiki/Zero_trust_security_model
+[labels]: https://kubernetes.io/docs/concepts/overview/working-with-objects/labels/
+[deployed and configured]: {{< relref "../getting-started/users#setup" >}}
+[Kuberenetes label selector]: https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.27/#labelselector-v1-meta
+[policyengine/examples]: https://github.com/clusterlink-net/clusterlink/tree/main/pkg/policyengine/examples

website/content/en/docs/main/concepts/services.md

@@ -6,14 +6,13 @@ weight: 30
 
 ClusterLink uses services as the unit of sharing between peers.
  One or more peers can expose an (internal) K8s Service to
- be consumed by other [peers][concept-peer] in the [fabric][concept-fabric].
+ be consumed by other [peers][] in the [fabric][].
  A service is exposed by creating an *Export* CR referencing it in the
  source cluster. Similarly, the exported service can be made accessible to workloads
  in a peer by defining an *Import* CR in the destination cluster[^KEP-1645].
  Thus, service sharing is an explicit operation. Services are not automatically
  shared by peers in the fabric. Note that the exporting cluster must be
- [configured as a peer][concept-peer-management] of the importing
- cluster.
+ [configured as a peer][] of the importing cluster.
 
 {{< notice info >}}
 Services sharing is done on a per namespace basis and does not require cluster wide privileges.
@@ -46,7 +45,7 @@ Orchestration of service sharing is the responsibility of users wishing to
 ## Prerequisites
 
 The following assume that you have `kubectl` access to two or more clusters where ClusterLink
- has already been [deployed and configured][getting-started-user-setup].
+ has already been [deployed and configured][].
 
 ### Exporting a service
 
@@ -96,8 +95,7 @@ Note that exporting a Service does not automatically make is accessible to other
  define at least one [access control policy][concept-policy] that allows
  access in the exporting cluster.
  In addition, users in consuming clusters must still explicitly configure
- [service imports](#importing-a-service) and [policies][concept-policy]
- in their respective namespaces.
+ [service imports][] and [policies][] in their respective namespaces.
 
 {{% expand summary="Example YAML for `kubectl apply -f <export_file>`" %}}
 
@@ -170,8 +168,7 @@ The ImportSpec defines the following fields:
  it to select a random and non-conflicting port, but there may be cases where
  you wish to assume responsibility for port selection (e.g., a-priori define
  local cluster Kubernetes NetworkPolicy object instances). This may result in
- [port conflicts](https://kubernetes.io/docs/concepts/services-networking/service/#avoid-nodeport-collisions)
- as is done for NodePort services.
+ [port conflicts][] as is done for NodePort services.
 - **Sources** (source array, required): references to remote exports providing backends
  for the Import. Each reference names a different export through the combination of:
   - *Peer* (string, required): name of ClusterLink peer where the export is defined.
@@ -188,7 +185,7 @@ The ImportSpec defines the following fields:
 
 As with exports, importing a service does not automatically make it accessible by
  workloads, but only enables *potential* access. To complete service sharing,
- you must define at least one [access control policy][concept-policy] that
+ you must define at least one [access control policy][] that
  allows access in the importing cluster. To grant access, a connection must be
  evaluated to "allow" by both egress (importing cluster) and ingress (exporting
  cluster) policies.
@@ -214,22 +211,26 @@ spec:
 ## Related tasks
 
 Once a service is exported and imported by one or more clusters, you should
- configure [polices][concept-policy] governing its access.
- For a complete end to end use case, refer to [iperf tutorial][tutorial-iperf].
+ configure [polices][] governing its access.
+ For a complete end to end use case, refer to [iperf tutorial][].
 
 [^KEP-1645]: While using similar terminology as the Kubernetes Multicluster Service
- enhancement proposal ([MCS KEP](https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api)),
- the ClusterLink implementation intentionally differs from and is not compliant with the
- KEP (e.g., there is no `ClusterSet` and "name sameness" assumption).
+ enhancement proposal ([MCS KEP][]), the ClusterLink implementation intentionally
+ differs from and is not compliant with the KEP (e.g., there is no `ClusterSet`
+ and "name sameness" assumption).
 
 [^multiport]: ClusterLink intentionally does not expose all service ports, as
  typically only a small subset in a multi-port service is meant to be user
  accessible, and other ports are service internal (e.g., ports used for internal
  service coordination and replication).
 
-[concept-fabric]: {{< relref "fabric" >}}
-[concept-peer]: {{< relref "peers" >}}
-[concept-peer-management]: {{< relref "peers#add-or-remove-peers" >}}
-[concept-policy]: {{< relref "policies" >}}
-[tutorial-iperf]: {{< relref "../tutorials/iperf" >}}
-[getting-started-user-setup]: {{< relref "../getting-started/users#setup" >}}
+[fabric]: {{< relref "fabric" >}}
+[peers]: {{< relref "peers" >}}
+[configured as a peer]: {{< relref "peers#add-or-remove-peers" >}}
+[policies]: {{< relref "policies" >}}
+[service imports]: #importing-a-service
+[port conflicts]: https://kubernetes.io/docs/concepts/services-networking/service/#avoid-nodeport-collisions
+[access control policy]: {{< relref "policies" >}}
+[iperf tutorial]: {{< relref "../tutorials/iperf" >}}
+[deployed and configured]: {{< relref "../getting-started/users#setup" >}}
+[MCS KEP]: https://github.com/kubernetes/enhancements/tree/master/keps/sig-multicluster/1645-multi-cluster-services-api