#Installation Guide

This guide installs Artifact Hub Shim as an ACP cluster plugin. The standard installation is completely offline and deploys the API, built-in catalog, and template-render extension into artifacthub-shim-system.

#Prerequisites

• You have ACP platform-administrator permissions and access to cluster plugin management.
• You have installed the violet CLI on an operation host that can access the ACP platform.
• You have downloaded the Artifact Hub Shim cluster plugin package to the operation host.
• Alauda DevOps Pipelines v4.0 or later is installed if the cluster will consume catalog resources through Tekton or Pipelines as Code.
• You can use kubectl with cluster-administrator permissions to verify the installation.

If the cluster already has a Tekton Hub or another Artifact Hub endpoint, record its configuration before changing consumers to Artifact Hub Shim.

#Upload the Cluster Plugin with Violet

Using violet push is the recommended way to upload the cluster plugin. The command transfers the packaged OCI chart and related images to the ACP global registry and creates or updates the ModulePlugin resource included in the package.

Run the following command from the directory containing the plugin package:

violet push <plugin-package>.tgz \
  --platform-address <platform-address> \
  --platform-username <platform-username> \
  --platform-password <platform-password> \
  --clusters <cluster-name> \
  --force

Replace the placeholders as follows:

Do not put platform credentials in scripts or source control. After the command completes, open Platform Management > Marketplace Management > Cluster Plugins and verify that Alauda Artifact Hub Shim is listed with the uploaded version.

#Install the Cluster Plugin from the Web Console

Use the following values for a standard initial installation:

For persistent storage, custom authentication, Ingress, and advanced runtime settings, see Chart Configuration.

1. Log in to ACP as a platform administrator.
2. Open the target cluster and navigate to cluster plugin management.
3. Select Alauda Artifact Hub Shim.
4. Select the latest available version approved for your environment.
5. Apply the recommended configuration above. If the target is the ACP global cluster, enable ACP Global Cluster Mode.
6. Start the installation and wait until the plugin reports Running.

Do not create or edit ModulePlugin, ModuleConfig, ModuleInfo, ClusterPluginInstance, or the derived AppRelease directly for a normal installation. ACP manages those resources as part of the cluster plugin lifecycle.

#Verify the Installation

The following commands assume the default install namespace, Helm release name, and generated resource names. If you customized any of these values, replace the namespace and resource names in the commands.

Check that the API Deployment is available:

kubectl get deployment -n artifacthub-shim-system
kubectl rollout status deployment/artifacthub-shim \
  -n artifacthub-shim-system \
  --timeout=5m

If you disabled Enable Template Render Extension during installation, skip the following command. Otherwise, verify the extension Deployment:

kubectl rollout status deployment/artifacthub-shim-extension \
  -n artifacthub-shim-system \
  --timeout=5m

Check the in-cluster Service and API health without exposing it externally:

kubectl get service artifacthub-shim-api -n artifacthub-shim-system

kubectl get --raw \
  '/api/v1/namespaces/artifacthub-shim-system/services/http:artifacthub-shim-api:80/proxy/healthz'

kubectl get --raw \
  '/api/v1/namespaces/artifacthub-shim-system/services/http:artifacthub-shim-api:80/proxy/readyz'

The health request should succeed, and the readiness response should contain "status":"ready".

Inspect the active snapshot when you need to verify source loading:

kubectl get --raw \
  '/api/v1/namespaces/artifacthub-shim-system/services/http:artifacthub-shim-api:80/proxy/api/v1/snapshot'

Do not publish the Service externally for Tekton integration. Tekton and Pipelines as Code should use the in-cluster Service URL.

#Connect Tekton

After the plugin is ready, configure TektonConfig and verify one remote Task. Standard installations use this endpoint:

http://artifacthub-shim-api.artifacthub-shim-system.svc.cluster.local

Follow Quick Start for the minimal validation or Configure Tekton Integration for Tekton and Pipelines as Code settings.

#Customize the Installation

• To add an internal catalog, see Configure Custom Git Repositories.
• To change storage or authentication, see Chart Configuration.
• To run multiple API replicas, follow High Availability before increasing replicaCount.
• To change log verbosity or encoding, see Logging.

#Uninstall Artifact Hub Shim

Uninstalling the plugin removes the local endpoint used by Tekton resolver, Pipelines as Code, and the DevOps Hub UI. It can interrupt pipelines and remove plugin-managed resources. Use the deletion risk information displayed by ACP cluster plugin management and follow your organization's approved uninstall procedure.

Before uninstalling, reconfigure or disable every consumer that points to the Artifact Hub Shim Service, back up user-managed repository definitions and credentials through an approved secure process, and ensure that no active PipelineRun or TaskRun depends on the endpoint. Never store exported credentials in source control.