DOCSEARCHbyAlgolia
Submit Docs

Skupper Documentation

repository·main·Indexed 20 days ago

https://github.com/skupperproject/skupper

Skupper is a tool for creating a Virtual Application Network (VAN) to enable secure, location-independent communication across hybrid multicloud environments, including VMs, bare metal, and various cloud providers. The documentation covers the installation and configuration of the Skupper controller and Network Observer via Helm or manifests, managing access types (NodePort, LoadBalancer, etc.), and bootstrapping non-Kubernetes sites using Podman, Docker, or Linux.

Tokens
34.1K
Snippets
106
Records
144
Agent score
69%

What's inside Skupper

  1. What is Skupper and how does it work?

    main

    Skupper enables the creation of a Virtual Application Network (VAN). This network allows for secure, location-independent communication between diverse systems, including:

    • Public cloud
    • Private cloud
    • Virtual machines (VMs)
    • Bare metal hosts
    • Mainframes

    Skupper v2 focuses on a declarative model, allowing applications and VANs to be deployed within fully automated frameworks using Custom Resource Definitions (CRDs) in Kubernetes or an equivalent implementation for Linux.

  3. How Skupper manages certificates internally

    main

    By default, Skupper manages its own certificate lifecycle by generating an internal CA named skupper-site-ca.

    Internal Directory Structure

    Generated certificates are stored in the runtime/ directory under the namespace home:

    • runtime/issuers/skupper-site-ca/: Contains the internal CA (tls.key, tls.crt, ca.crt).
    • runtime/certs/: Contains server certificates (named after the RouterAccess or spec.tlsCredentials) and client certificates (prefixed with client-).

    Certificate Generation Logic

    1. CA: Skupper generates skupper-site-ca to sign other certificates.
    2. Server Certificates: If RouterAccess is defined, Skupper generates a certificate valid for RouterAccess.spec.bindHost and all RouterAccess.spec.subjectAlternativeName entries.
    3. Client Certificates: Skupper generates client certificates signed by skupper-site-ca to be used by other sites for establishing links. These are stored in runtime/certs/ with a client- prefix.
    shell
runtime/
├── certs
│   ├── my-router-access
│   │   ├── ca.crt
│   │   ├── tls.crt
│   │   └── tls.key
│   └── client-my-router-access
│       ├── ca.crt
│       ├── tls.crt
│       └── tls.key
└── issuers
    └── skupper-site-ca
        ├── ca.crt
        ├── tls.crt
        └── tls.key

  4. How TLS credential rotation works in Skupper

    main

    Skupper uses TLS connections for both internal coordination and application traffic proxying across Sites via Links. When you rotate the TLS credentials (by updating the associated Kubernetes Secret), Skupper initiates an active migration:

    1. Link Resources: Skupper proactively begins migrating to the new credentials by opening new TLS connections to peers.
    2. RouterAccess: New connections use the updated credentials immediately, while existing connections are maintained to prevent application disruption.

    Skupper automatically watches for changes to Secrets used for TLS Credentials and prefers the new set immediately upon update.

  5. Configure a Skupper Connector

    main

    A Connector allows a site to connect to a service exposed by another site. It requires a host, port, and a routingKey that matches the routingKey defined in the remote site's Listener.

    apiVersion: skupper.io/v2alpha1
kind: Connector
metadata:
  name: backend
spec:
  host: 127.0.0.1
  port: 9090
  routingKey: backend-8080

  6. How Skupper handles link creation and TLS service updates without router restarts

    main

    To prevent operational interruptions, Skupper is designed to avoid restarting the router when performing high-frequency operations such as:

    1. Creating links: Previously, creating links required a router restart to append volumes with associated secrets.
    2. Enabling TLS on services: Creating or exposing services with the TLS flag enabled previously required a router restart to append new volumes.

    Instead of restarts, Skupper uses a config-sync sidecar. This sidecar manages the availability of certification files to the router via a shared volume and updates both the bridge configuration and the connectors required for new links dynamically.

  7. Understanding Skupper service bindings (Ingress and Egress)

    main

    In Skupper, service bindings are the configurations that define how traffic flows between sites:

    • Ingress binding: Determines how a Skupper service is invoked (how external traffic enters the site).
    • Egress binding: Determines which processes or services that invocation may be routed to (where the traffic goes once it enters the site).

    Note: The project is moving away from using Kubernetes annotations (like skupper.io/proxy) for these configurations in favor of explicit resources to improve clarity and compatibility with GitOps workflows.

  8. Link Skupper sites using AccessGrant and AccessToken

    main

    To establish a secure link between two sites without the CLI, follow this handshake pattern:

    1. Create an AccessGrant: In the site that wants to receive the connection (the consumer site), apply an AccessGrant resource.
    2. Wait for Readiness: Monitor the AccessGrant status until the url, ca, and code fields are populated.
    3. Create an AccessToken: In the site that wants to initiate the connection (the provider site), create an AccessToken resource. You must copy the ca, code, and url values from the AccessGrant status into the AccessToken specification.
    4. Apply: Apply the AccessToken to the provider site to complete the link.

  9. Key features of Skupper v2

    main

    Skupper v2 introduces several architectural improvements over v1:

    • Declarative Interfaces: Uses Kubernetes Custom Resource Definitions (CRDs) for intuitive management, with a Linux equivalent for non-Kubernetes environments.
    • Improved Architecture: Refined primary components including the controller, CLI, and non-kube executable.
    • Flexible PKI: A PKI implementation that allows users to provide their own certificates.
    • Separated Observability: A network collector and console that are deployed independently from the core site components.
    • Centralized Integration: Simpler methods for defining application networks centrally.

  10. Configure Authentication Strategies

    main

    The network observer uses a reverse proxy to handle authentication and TLS termination. Supported strategies include:

    • basic: Uses Nginx as a proxy. It can be configured with user-provided htpasswd file contents or a specific secretName. This is the default for the Helm chart if not specified otherwise.
    • openshift: Uses an oauth2-proxy to authenticate against the cluster's identity provider. Note: This strategy only works when using the OpenShift Route ingress type.

  11. How Skupper uses TLS for secure communication

    main

    Skupper uses mutual TLS (mTLS) to secure communications between Skupper routers via Links.

    In this model:

    • The linking site (the site initiating the Link) acts as the TLS client.
    • The accepting site (the site with a RouterAccess) acts as the TLS server.

    Requirements for successful connection:

    1. Server Validation: The linking site validates the server's certificate against its own trusted CAs.
    2. Client Validation: The accepting site validates the incoming client certificate against its trusted CAs.
    3. TLS Passthrough: Any intermediate load balancers between Sites must use TLS passthrough. Terminating TLS at a load balancer will prevent routers from authenticating one another.
    4. Hostname Validation: The RouterAccess certificate must be valid for the host(s) in the Link/RouterAccess endpoints.
    WARNING

    The Skupper router ignores Subject Alternative Name (SAN) IP entries during hostname validation. The Skupper controller works around this by adding IPs as DNS entries.

  12. Default TLS Management in Kubernetes

    main

    When running in Kubernetes, the Skupper controller automates TLS credential management using a site-scoped CA model (each site acts as its own root of trust).

    RouterAccess (Server) Credentials

    When a Site is initialized with link access enabled:

    1. Skupper creates a RouterAccess resource named skupper-router.
    2. Skupper issues a self-signed CA named skupper-site-ca (valid for 5 years).
    3. Skupper issues a skupper-site-server certificate (valid for 5 years) signed by skupper-site-ca.
    4. The skupper-site-ca certificate is embedded in the ca.crt field of the skupper-site-server secret.

    Link (Client) Credentials

    When a Link is created (via skupper link generate or AccessToken redemption):

    1. The accepting Site's controller issues a new client TLS certificate signed by that site's skupper-site-ca.
    2. The skupper-site-ca public key is embedded into the ca.crt field of the client certificate.
    3. The certificate is transported to the linking Site (manually or via HTTPS) and saved as a Secret.
    4. The Link's spec tlsCredentials field is updated to reference this Secret.