While setting up a Puppet agent on a Windows Server 2008 R2 machine connected to an existing Puppet infrastructure, I encountered a persistent error during agent initialization:

Error 400 on SERVER: The environment must be purely alphanumeric, not 'puppet-ca'

This occurred despite following standard Puppet installation procedures, suggesting a configuration mismatch between the agent and master.

The infrastructure consisted of:

• Puppet master: CentOS 7 (managed by infrastructure team)
• Puppet agent: Windows Server 2008 R2 SP1
• Puppet versions: 5.5.1 (master) and 5.5.3 (agent)

The error stems from Puppet's strict validation of environment names. While troubleshooting, I discovered:

1. The master's puppet.conf contained legacy CA configuration:

[master]
ca = true
ca_name = puppet-ca

2. The agent was incorrectly inheriting this as an environment name during certificate generation

For the Windows agent, we needed to explicitly set the environment:

# In C:\ProgramData\PuppetLabs\puppet\etc\puppet.conf
[agent]
environment = production
server = puppet-master.example.com

On the Puppet master, we updated the CA configuration:

# In /etc/puppetlabs/puppet/puppet.conf
[master]
ca = true
dns_alt_names = puppet,puppet-master,puppet-master.example.com

After configuration changes:

1. On the agent:

puppet agent -t --environment production

2. Check certificate signing on master:

puppet cert list
puppet cert sign <agent_hostname>

For environments requiring multiple certificate authorities:

# In hiera.yaml on master
puppet::server::ca: true
puppet::server::ca_name: "%{::trusted.certname}"

• Puppet environments must be alphanumeric (regex: ^[a-zA-Z0-9_]+$)
• Windows agents may inherit unexpected settings from master templates
• Always verify environment parameters before first agent run

---

While setting up a new Puppet agent on Windows Server 2008 R2, I kept hitting this roadblock:

Error 400 on SERVER: The environment must be purely alphanumeric, not 'puppet-ca'

The infrastructure team had already configured the Puppet master, and my task was simply to join this new node to the existing Puppet infrastructure.

After digging through Puppet's documentation and source code, I discovered this occurs when:

• The agent tries to request a certificate from a CA server
• The environment name contains invalid characters (hyphens in this case)
• Puppet enforces strict alphanumeric validation for environment names

Checking the puppet.conf file revealed:

[agent]
environment = puppet-ca

The hyphen in the environment name violates Puppet's naming conventions.

Here's how to properly configure it:

[agent]
environment = puppetca  # or production, development, etc.
certname = hostname.domain.com
server = puppet-master.domain.com

Key points:

• Environment names must match ^[a-zA-Z0-9_]+$ regex
• Common production environments: production, staging, development
• Never use special characters or spaces

After making changes:

1. Restart the Puppet agent service: net stop puppet && net start puppet
2. Run manually: puppet agent -t --debug
3. Check certs: puppet cert list -a on master

To avoid similar issues:

# validation.rb
def validate_environment(env)
  raise ArgumentError unless env =~ /^[a-zA-Z0-9_]+$/
end

Consider implementing such validation in your Puppet module code.