Image Library Service Certificate Configuration
Overview
The Image Library Service uses a TLS certificate to secure image upload and retrieval traffic. If your browser or CLI client does not trust that certificate, image uploads from the UI will be blocked, and CLI uploads without the --insecure flag will fail.
Private Cloud Director supports two deployment models with different certificate management paths:
SaaS: Platform9 operates the management plane. The Image Library Service endpoint certificate is managed by Platform9. You accept the certificate in your browser; you do not modify management-plane certificates directly.
Self-Hosted: You operate the management plane on-premise. You can supply your own custom certificate and apply it using
airctl.
In this guide, you will trust or configure the Image Library Service certificate for your deployment model so that image uploads and VM provisioning succeed.
If you use Google Chrome, your browser may also prompt you to grant Local Network Access before the Image Library Service is reachable from the UI; see Local Network Access in Chrome below.
SaaS Deployments
In SaaS deployments, the Image Library Service host uses a self-signed certificate for the image upload endpoint. You must accept this certificate in your browser before you can upload images through the UI.
Accept the Certificate in Your Browser
Sign in to the Private Cloud Director UI.
Navigate to Images. If the certificate has not been trusted, a banner or notification appears that reads Action Required: Trust Certificate.
Click the link in the notification. A new browser tab opens to the Image Library Service endpoint.
In the browser's security warning page, expand Advanced (or Details, depending on your browser) and click the link to proceed to the site.
After accepting the certificate, close the tab and return to the Images page. The upload controls should now be active.
For detailed steps for each browser, see Accept Certificate Authority.
CLI Uploads (SaaS)
When using the pcdctl CLI to upload images in a SaaS deployment, include the --insecure flag to bypass certificate verification for the Image Library endpoint:
This flag applies to the image endpoint only. It does not affect Identity Service authentication.
Management-Plane Certificate Changes (SaaS)
SaaS deployments only
In SaaS deployments, Platform9 manages the management-plane certificates. You cannot modify these certificates directly. If you need a custom or CA-signed certificate for the Image Library Service endpoint in a SaaS deployment, contact Platform9 Support.
Self-Hosted Deployments
In Self-Hosted deployments, you have full control over management-plane certificates and can supply a custom certificate.
Accept the Default Self-Signed Certificate
If you are using the default self-signed certificate generated during installation, follow the same browser-acceptance steps as for SaaS deployments (see above). This is the quickest path for small or evaluation deployments.
For CLI uploads, use the --insecure flag with pcdctl image create as shown in the SaaS section above.
Configure a Custom Certificate
To replace the default self-signed certificate with a CA-signed or custom certificate, use the airctl renew-certs command. This updates the management-plane certificate, which is then used by the Image Library Service and other services.
For full instructions, see Using Custom Certificates.
After applying a new certificate, verify that the Image Library Service endpoint is reachable:
If you configured a CA-signed certificate, this request should succeed without the -k flag. If it returns a certificate error, confirm that the certificate's Subject Alternative Names (SANs) include the Image Library host's FQDN or IP address.
Verify Certificate Trust After Changes
After updating certificates in a Self-Hosted deployment, restart the Image Library Service on the affected host:
Then re-check the endpoint health and attempt a test upload to confirm the change took effect.
Local Network Access in Chrome
The Image Library Service endpoint is reached over a private IP address on your network, for example https://<image-library-host>:9494. Some versions of Chrome ask for an additional, one-time permission before a website can reach a host on your local network. If your browser prompts you for Local Network Access, you must grant it before the PCD UI can reach the Image Library Service, even after you have already trusted its certificate.
When the Prompt Appears
Chrome shows the Local Network Access prompt the first time the PCD UI tries to reach the Image Library Service host, for example when you open the Add Image form or start an image upload. Select Allow to grant access.
Action Required in the Add Image Form
The PCD UI checks whether it can reach the Image Library Service endpoint when you open the Add Image form. If the check fails, a red Action Required heading appears at the top of the form with a count of outstanding items. Select the heading to open the Action Required dialog, which lists the actions needed to access the Image Library endpoint.
When Chrome has not granted Local Network Access, the dialog includes an Allow Local Network Access item that asks you to allow Local Network Access in your browser so the page can connect to the Image Library endpoint. This item always appears together with another item, either Trust Image Library Certificate or Image Library Host Not Reachable, because the UI cannot tell a blocked local network request apart from an untrusted certificate or an unreachable host. Seeing the Allow Local Network Access item does not by itself mean that Local Network Access is the cause. Check the browser permission first, then work through the other item if the heading remains.
The UI rechecks the endpoint every 30 seconds and when you refresh the page. After you grant Local Network Access, the Allow Local Network Access item is removed as soon as the browser reports the new permission state, and the Action Required heading clears after the next successful check.
Re-Enable a Blocked Permission
If you dismissed or blocked the prompt, grant the permission from Chrome's site settings:
In Chrome, select the icon to the left of the address bar (the padlock or tune icon) while viewing the PCD UI.
Select Site settings.
Under Permissions, find Local network access and set it to Allow.
Reload the PCD UI and open the Add Image form again.
Troubleshooting Certificate Issues
UI upload button is not active; certificate warning shown
Certificate not accepted in this browser
Follow the browser-acceptance steps above.
SSL: CERTIFICATE_VERIFY_FAILED in CLI output
--insecure flag omitted, or a CA-signed cert whose CA is not trusted
Add --insecure, or add the CA certificate to the system trust store.
Certificate accepted, but upload still blocked
Browser cached an older, untrusted state
Clear the browser cache or retry in a private window.
Custom certificate applied but endpoint still shows old cert
Service not restarted after cert change
Run sudo systemctl restart pf9-glance-api on the Image Library host.
Action Required still shows in the Add Image form in Chrome, even after the certificate is trusted
Local Network Access permission not granted in Chrome
Grant Local Network access; see Local Network Access in Chrome above.
For general Image Library Service health checks, see Image Library Service Endpoint Health.
Last updated
Was this helpful?