diff --git a/src/content/menu.json b/src/content/menu.json index f8167db0..577022e6 100644 --- a/src/content/menu.json +++ b/src/content/menu.json @@ -304,6 +304,10 @@ "title": "Upstreams", "path": "/repositories/upstreams" }, + { + "title": "Connected Repositories", + "path": "/repositories/connected-repositories" + }, { "title": "Privileges", "path": "/repositories/repository-privileges" diff --git a/src/content/repositories/connected-repositories/images/connected-repository-config.png b/src/content/repositories/connected-repositories/images/connected-repository-config.png new file mode 100644 index 00000000..db911d73 Binary files /dev/null and b/src/content/repositories/connected-repositories/images/connected-repository-config.png differ diff --git a/src/content/repositories/connected-repositories/images/connected-repository-connect.png b/src/content/repositories/connected-repositories/images/connected-repository-connect.png new file mode 100644 index 00000000..1cfd1fc6 Binary files /dev/null and b/src/content/repositories/connected-repositories/images/connected-repository-connect.png differ diff --git a/src/content/repositories/connected-repositories/index.mdx b/src/content/repositories/connected-repositories/index.mdx new file mode 100644 index 00000000..5f3027af --- /dev/null +++ b/src/content/repositories/connected-repositories/index.mdx @@ -0,0 +1,119 @@ +import { Note, BlockImage } from '@/components' + +import connectedRepoConfig from './images/connected-repository-config.png' +import connectedRepoConnect from './images/connected-repository-connect.png' + +# Connected Repositories + + +Connected Repositories is in Early Access (EA) and is currently supported for Maven, Docker, Python and NPM. Please reach out to us if you are interested in trying it out or have feedback to share. + + +Connected Repositories allows you to natively link multiple repositories together within a workspace, making packages from all connected repositories available through a single URL. + +## How It Works + +When repositories are connected, package resolution happens within the context of a single request. There is no redirection between repositories, and packages pushed to any connected repository are immediately visible to consumers of the primary repository — no indexing delay. + +This is a significant improvement over Cloudsmith-to-Cloudsmith upstreams, which have two notable drawbacks: + +- **Delayed availability**: Packages in upstream Cloudsmith repositories only become visible after the indexing cycle runs (typically every two hours). Packages are not available immediately after being pushed. +- **Double requests**: Each package download triggers a request to the primary repository and a redirect to the upstream repository, resulting in two requests per download. This reduces performance. + +Connected Repositories resolve both of these issues: + +- Packages are available instantaneously across all connected repositories as soon as they are pushed or updated. +- Package resolution happens inside a single request with no redirection, significantly improving performance. + +## Priority + +Each connected repository is assigned an integer priority, which determines the order in which repositories are evaluated during package resolution. This is important when the requested package exists in multiple connected repositories. + +Resolution order follows `1..n`, where `1` is the highest priority. When multiple connected repositories share the same priority value, the configuration creation date is used as a tiebreaker. + +## Upstream Inheritance + +Upstreams configured on connected repositories are automatically available through the primary repository. For example, if Repository A is connected to Repository B, and Repository B has upstreams pointing to PyPI and PyTorch, consumers of Repository A can resolve packages from both of those upstreams. + +Packages fetched from inherited upstreams are cached in the repository where the upstream is configured (i.e., Repository B in this example). + +When blending upstreams across connected repositories, relative priorities are dynamically calculated based on the priority of each connection. For example, if Repository A has two connections each with priority `1` on their respective repositories, the upstream from the higher-priority connection will be assigned relative priority `1`, and the upstream from the lower-priority connection will be assigned relative priority `2`. + +## Requirements + +To create a connected repository configuration, you must have: + +- **Administrator** privileges on the repository you are creating the connection on (the "primary" repository). +- At least **Read** privileges on the repository you are connecting to. + +This mirrors the permission model used for upstreams. + +## Supported Formats + +| Format | Connected Repositories Support | +| :----- | :----------------------------- | +| Maven | ✅ | +| Docker | ✅ | +| Python | ✅ | +| NPM | ✅ | + + +Support for additional formats is planned. + +## Configuring Connected Repositories + +Connected repositories can be configured via the UI or API. + +### Using the UI + +Navigate to the Sources tab on the repository you want to configure as the primary repository where you will find the **Connected Repositories** settings. + + +Select the target repository and assign it a priority to create the connection. + + +### Using the API + + +The Connected Repositories API is currently unlisted from the public OpenAPI specification while the feature is in Early Access. It will be made public in a future release, enabling language binding generation and support in the Cloudsmith CLI and Terraform provider. + + +The following operations are available: + +| Operation | Description | +| :-------- | :---------- | +| Create | Create a new connected repository configuration | +| List | List all connected repository configurations for a repository | +| Update | Update the priority or target of an existing configuration | +| Delete | Remove a connected repository configuration | + +## Behavior and Considerations + +### Access Control + +Connecting Repository A to Repository B gives consumers of Repository A implicit access to view and download packages within Repository B via native tooling. + +### Audit Logs + +Audit log entries are created when connected repository configurations are created, updated, or deleted. + +### Download Attribution + +When a package download occurs through the primary repository for a package that belongs to a connected repository, the client log entry is produced for the primary repository. The individual package download count is incremented on the package in the repository where it resides. + + +Client logs do not currently indicate that a package was resolved through a connected repository. Work is planned to add connected repository attribution to download logs. + + +### Package Signatures + +Connected repositories do not cache packages. Package signatures are sourced from the repository where the package belongs and are signed using that repository's key. Policies continue to apply to packages within the repository they belong to. + +## Current Limitations + +The following is a non-exhaustive list of known limitations during Early Access: + +- **OSS repositories**: Connected repository configurations cannot be created on OSS repositories, or targeting OSS repositories. +- **Cross-workspace**: Connected repositories can only be configured between repositories within the same workspace. +- **Download log attribution**: Client logs do not yet attribute package downloads to connected repositories. +- **Repository restrictions**: Repository level restrictions such as Geo/IP Rules and EULA enforcement must be defined on the source repository. These restrictions are not inherited from connected repositories. diff --git a/src/content/repositories/index.mdx b/src/content/repositories/index.mdx index 54279721..30d7cb83 100644 --- a/src/content/repositories/index.mdx +++ b/src/content/repositories/index.mdx @@ -37,5 +37,6 @@ Use the top menu items to access the controls available: |[Geo/IP Rules](/policy-management/geoip-rules) | Manage download permissions by IP and/or Geographic area| |[Retention Rules](/artifact-management/retention-rules) | Manage the size of your repositories with retention settings| |[Upstream Proxying](/repositories/upstreams)|Configure upstream sources for this repository| +|[Connected Repositories](/repositories/connected-repositories)|Link multiple repositories together for unified package resolution| |[Webhooks](/developer-tools/webhooks)|Create and configure webhooks to allow external tools/systems to see your Cloudsmith events| {/* |[Package Logs](/logs-and-observability/package-logs)|View logs of package events for this repository| */}