Defined Type: dehydrated::certificate

Defined in:
manifests/certificate.pp

Summary

Creates key & csr and request the certificate.

Overview

Triggers key and csr generation and requests the certificate via the host configured in $dehydrated_host. This is the main defined type to use if you want to have a certificate. Together with the defaults in the dehydrated class you should have everything to make requesting certificates possible. Especially the dehydrated::certificate::* types do not have a public API and can change without warning. Don't rely on them. Dehydrated::Certificate[$dn] is also what you want to use to subscribe to if you want to restart services after certificates have been installed/updated.

Examples:

dehydrated::certificate { 'test.example.com': }

Parameters:

  • dn (Dehydrated::DN) (defaults to: $name) —

    The main distinguished name to use for the certificate. Defaults to $name.

  • base_filename (String) (defaults to: regsubst($dn, '^\*', '_wildcard_')) —

    The base part of the filename of all related files. For wildcard certificates the * is replaced by wildcard. Feel free to use whatever a valid filename is.

  • subject_alternative_names (Array[Dehydrated::DN]) (defaults to: []) —

    To request a SAN certificate, pass an array with the alternative names here. The main $dn will be added automatically.

  • challengetype (Dehydrated::Challengetype) (defaults to: $dehydrated::challengetype) —

    Default challengetype to use. Defaults to $dehydrated::challengetype, which defaults to 'dns-01'. You can specify a different challengetype for each certificate here.

  • algorithm (Dehydrated::Algorithm) (defaults to: $dehydrated::algorithm) —

    Algorithm / elliptic-curve you want to use. Supported: rsa, secp384r1, prime256v1. Defaults to $dehydrated::algorithm, which defaults to 'rsa'. You can specify a different algorithm for each certificate here.

  • key_size (Integer[768]) (defaults to: $dehydrated::key_size) —

    Size of the key if we create a new one. Only used if algorithm is 'rsa'.

  • dh_param_size (Integer[768]) (defaults to: $dehydrated::dh_param_size) —

    Size of the DH params we should generate. Defaults to $dehydrated::dh_param_size, which defaults to 2048. You can specify a different DH param size for each certificate here.

  • dehydrated_host (Stdlib::Fqdn) (defaults to: $dehydrated::dehydrated_host) —

    $trusted['certname'] of the host which is responsible to request the certificates from the Let's Encrypt CA. Defaults to $dehydrated::dehydrated_host where you can configure your default.

  • dehydrated_environment (Hash) (defaults to: $dehydrated::dehydrated_environment) —

    Hash with the environment variables to set for the $dehydrated_domain_validation_hook and also for running the hook in dehydrated. Defaults to $dehydrated::dehydrated_environment, empty by default.

  • dehydrated_hook (Optional[Dehydrated::Hook]) (defaults to: $dehydrated::dehydrated_hook) —

    Name of the hook script you want to use. Can be left on undef if http-01 is being used as challengetype to use the built-in http-01 implementation of dehydrated. Defaults to $dehydrated::dehydrated_hook, which will use "$challengetype.sh" if the challengetype is not http-01.

  • letsencrypt_ca (String) (defaults to: $dehydrated::letsencrypt_ca) —

    Defines the CA you want to use to request certificates. If you want to use a non-supported CA, you need to configure it in $dehydrated::letsencrypt_cas on your $dehydrated_host. Normally, the following CAs are pre-configured: staging, production, v2-staging, v2-production Defaults to $dehydrated::letsencrypt_ca, which points to v2-production.

  • dehydrated_domain_validation_hook (Optional[Dehydrated::Hook]) (defaults to: $dehydrated::dehydrated_domain_validation_hook) —

    Name of the hook script to run before dehydrated is actually executed. Used to check if a domain is still valid or if you are allowed to modify it. Or whatever else you want to do as preparation. Good thing to use before running into limits by trying to request certificates for domains you don't own. Defaults to $dehydrated::dehydrated_domain_validation_hook where you can configure the default for your setup.

  • key_password (Optional[String]) (defaults to: undef) —

    If your key should be protected by a password, specify it here.

  • preferred_chain (Optional[String]) (defaults to: $dehydrated::preferred_chain) —

    Preferred letsencrypt CA chain you want to use



76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
 
# File 'manifests/certificate.pp', line 76

define dehydrated::certificate (
  Dehydrated::DN $dn = $name,
  String $base_filename = regsubst($dn, '^\*', '_wildcard_'),
  Array[Dehydrated::DN] $subject_alternative_names = [],
  Dehydrated::Challengetype $challengetype = $dehydrated::challengetype,
  Dehydrated::Algorithm $algorithm = $dehydrated::algorithm,
  Integer[768] $key_size = $dehydrated::key_size,
  Integer[768] $dh_param_size = $dehydrated::dh_param_size,
  Stdlib::Fqdn $dehydrated_host = $dehydrated::dehydrated_host,
  Hash $dehydrated_environment = $dehydrated::dehydrated_environment,
  Optional[Dehydrated::Hook] $dehydrated_hook = $dehydrated::dehydrated_hook,
  String $letsencrypt_ca = $dehydrated::letsencrypt_ca,
  Optional[Dehydrated::Hook] $dehydrated_domain_validation_hook = $dehydrated::dehydrated_domain_validation_hook,
  Optional[String] $key_password = undef,
  Optional[String] $preferred_chain = $dehydrated::preferred_chain,
) {
  if ! defined(Class['dehydrated']) {
    fail('You must include the dehydrated base class first.')
  }

  require dehydrated::setup
  require dehydrated::params

  # ensure $dn is also in subject_alternative_names
  $_subject_alternative_names = unique(flatten([$dn, $subject_alternative_names]))

  $domain_config = {
    $dn => {
      'subject_alternative_names'         => $_subject_alternative_names,
      'base_filename'                     => $base_filename,
      'dh_param_size'                     => $dh_param_size,
      'challengetype'                     => $challengetype,
      'dehydrated_host'                   => $dehydrated_host,
      'dehydrated_environment'            => $dehydrated_environment,
      'dehydrated_hook'                   => $dehydrated_hook,
      'dehydrated_domain_validation_hook' => $dehydrated_domain_validation_hook,
      'letsencrypt_ca'                    => $letsencrypt_ca,
      'preferred_chain'                   => $preferred_chain,
    },
  }

  $json_fragment = to_json($domain_config)
  ::concat::fragment { "${trusted['certname']}-${dn}" :
    target  => $dehydrated::params::domainfile,
    content => $json_fragment,
    order   => '50',
  }

  dehydrated::certificate::csr { $base_filename :
    dn                        => $dn,
    subject_alternative_names => $subject_alternative_names,
    key_password              => $key_password,
    algorithm                 => $algorithm,
    size                      => $key_size,
  }

  $ready_for_merge = $dn in $dehydrated::ready_for_merge

  if $ready_for_merge {
    dehydrated::certificate::deploy { $dn :
      key_password => $key_password,
    }
  }
}