Skip to main content

Test-Phase Connectivity Requirements

BUILD-stage custom components run before the TEST stage. If a component changes certain guest-level settings — networking, remote-management agents, or the SSH/remote-access daemon — ImageFactory may no longer be able to reach the resulting VM once the TEST stage starts. When this happens today, the failure surfaces as a generic error rather than a specific explanation, so it's important to know the requirements up front rather than debug them after the fact.

How ImageFactory connects during the TEST stage​

After a BUILD completes, ImageFactory launches a fresh VM from the built image and connects to it to run test components and compliance checks. The exact mechanism differs by provider:

  • AWS: Connectivity is handled entirely through the AWS Systems Manager (SSM) agent, which ships pre-installed on standard AWS AMIs. No SSH or RDP/WinRM access is required for test execution.
  • Azure: A cloud provider agent (the Azure guest agent) registers the instance for remote management. For Linux images specifically, ImageFactory also performs an additional SSH-based connectivity check using a provisioning account and password authentication on port 22.
  • GCP: For Linux images, ImageFactory uses SSH (key-based authentication, injected via instance metadata) to bootstrap remote management — there is no fallback mechanism if this fails. For Windows images, a native startup-script mechanism handled by the GCP guest agent is used instead.
  • Windows (any provider): Test components run through the platform's remote-management agent, not WinRM — even though security group / firewall rules for RDP and WinRM ports may be present for general access purposes.

General pitfalls (all providers)​

Regardless of cloud or OS, avoid the following in a BUILD-stage component:

  • Disabling, masking, or uninstalling the cloud provider's remote-management agent (e.g. the SSM agent or its Windows equivalent). This agent is what ImageFactory uses to reach the VM during TEST, independent of any other connectivity you configure.
  • Blocking outbound HTTPS or DNS resolution needed to reach cloud management endpoints. If a component tightens egress filtering or removes trusted CA certificates, agent registration and heartbeat can fail silently.
  • Removing core package-manager or service-manager tooling on Linux (e.g. rpm/dpkg, systemd/snapd). Some providers install or restart the management agent lazily, and this tooling may be needed for that step to succeed.
  • Deleting or corrupting the management agent's local state/credentials directory as part of an "aggressive cleanup" script.

Provider- and OS-specific requirements​

ProviderOSConnectivity mechanismDo NOT in a BUILD component...
AWSLinux / WindowsCloud management agent only (pre-installed)Uninstall or disable the pre-installed management agent.
AzureLinuxGuest agent registration + SSH (password auth, port 22)Disable or mask the guest agent; disable sshd or set PasswordAuthentication no; leave a host firewall rule (iptables/firewalld/ufw) that blocks port 22 in the finished image.
AzureWindowsGuest agent registrationDisable or stop the Windows guest agent service.
GCPLinuxGuest agent + SSH (key-based, port 22) — no fallbackDisable sshd; disable or remove the guest agent; block port 22 at the host firewall level; disable metadata-based SSH key provisioning.
GCPWindowsGuest agent startup-script mechanismDisable or stop the guest agent service.
No fallback on GCP Linux

For GCP Linux images, SSH is the only way ImageFactory bootstraps remote management on a fresh test VM. If a BUILD component breaks SSH (disables sshd, removes the guest agent, or firewalls off port 22), the failure isn't limited to the TEST stage — the whole build fails, because there's no other path to reach the instance.

Why isn't the login account itself the risk?​

You might expect the provisioning account used for these checks (for example, an account used only for the Azure or GCP connectivity check) to be something a cleanup script could accidentally remove. It isn't a risk in practice: that account is not baked into the image at all. It's created fresh by the guest agent when ImageFactory boots a brand-new VM from your finished image for the TEST stage. There is nothing for a BUILD-stage account-cleanup script to remove. The actual risk is the underlying mechanism that creates and authenticates that account on first boot — the guest agent, sshd, and the firewall state you leave in the image — which is why the table above focuses on services and firewall rules rather than user accounts.

If a test fails with no clear reason​

If a TEST-stage failure shows a generic or internal error with no further detail, check whether a recently added or changed BUILD-stage component touches any of the services, daemons, or firewall rules listed above before assuming the problem is a networking outage. This is also why ImageFactory's own hardening rules maintain a set of documented exceptions for rules that would otherwise break connectivity — see CIS Hardening Exceptions. The same category of risk applies to your own custom components, just without an automatic exception process.

Related pages