NGINX Frontend - ghomem/legacy_puppet_infrastructure GitHub Wiki

NGINX Frontend

The frontends can be used in conjunction with the static servers. If you intend to do that, you can use the nginx_frontend class combined with the nginx_frontend_domain and nginx_static_domain defined types, but not with the nginx_static class because both classes are responsible for the deletion of the default configuration file that is created by the nginx package, which can only happen once.

Frontend for a Single App

This is the simplest use case:

class { 'puppet_infrastructure::nginx_frontend':
  domain                  => 'example.com',
  frontend_sslprefix      => 'example.com',
  backend_hosts_and_ports => ['127.0.0.1:8000', ],
  backend_protocol        => 'http',
}

This frontend reverse proxies an application that is running on port 8000 at localhost. The servers created are:

HTTP server on http://example.com that redirects to HTTPS;
HTTP www server on http://www.example.com that redirects to HTTPS www;
Default server that returns a '404' when someone tries to access the app by IP, accepts both HTTP and HTTPS;
Main HTTPS server, serves HTTPS requests with and without www, i.e., https://example.com and https://www.example.com

In addition, the ssl certificates and private key are installed, because the class has a parameter called $manage_ssl, which is true by default. They are expected to be found at /etc/puppetlabs/puppet/extra_files/ssl/ and named example.com.XXX where XXX can be key, crt and intermediate.crt.

Note: the server that is created by default by the nginx package is disabled by any nginx_frontend configuration.

You can find a complete node declaration example for a single application here: https://bitbucket.org/asolidodev/puppet_infrastructure/src/stable/node-examples/nginx-frontend/nginx-frontend01.pp

Frontend to Main Website with Secondary Domains

This is the simplest use case for a main website with 2 subdomains:

class { 'puppet_infrastructure::nginx_frontend':
  domain                  => 'example.com',
  frontend_sslprefix      => 'example.com',
  backend_hosts_and_ports => ['127.0.0.1:8000', ],
  backend_protocol        => 'http',
}

puppet_infrastructure::nginx_frontend_domain { 'mail.example.com':
  domain                                => 'mail.example.com',
  frontend_sslprefix                    => 'example.com',
  backend_hosts_and_ports               => ['127.0.0.1:8001', ],
  backend_protocol                      => 'http',
  manage_ssl                            => false,
  redirect_http_www_to_https_www_create => false,
  server_https_www_create               => false,
}

puppet_infrastructure::nginx_frontend_domain { 'chat.example.com':
  domain                                => 'chat.example.com',
  frontend_sslprefix                    => 'chat.example.com',
  backend_hosts_and_ports               => ['127.0.0.1:8002', ],
  backend_protocol                      => 'http',
  manage_ssl                            => true,
  redirect_http_www_to_https_www_create => false,
  server_https_www_create               => false,
}

This frontend serves 3 apps, all on localhost, on ports 8000, 8001 and 8002. Besides the 4 servers described previously, these additional servers are created:

HTTP server that redirects to HTTPS on http://mail.example.com;
HTTP server that redirects to HTTPS on http://chat.example.com;
Main HTTPS server for https://mail.example.com, only serves requests without www;
Main HTTPS server for https://chat.example.com, only serves requests without www.

In addition, the ssl certificates and private key are installed. It's expected that the example.com certificate is multi-domain and includes www.example.com and mail.example.com.
Unlike mail.example.com, chat.example.com manages its own certificates and keys and they are expected to be found at /etc/puppetlabs/puppet/extra_files/ssl/ and named chat.example.com.XXX where XXX can be key, crt and intermediate.crt.
$manage_sslis false by default in the defined type, and true by default in the class.

You can find a complete node declaration example for multiple applications, using very similar code than the one we have above here: https://bitbucket.org/asolidodev/puppet_infrastructure/src/stable/node-examples/nginx-frontend/nginx-frontend02.pp

Multiple Frontends to Multiple Domains on the same Virtual Machine

This is a complete example, including the node declaration, like you would do on your machine:

node 'virtualmachine' {
  # Basic desirable configuration for a generic Ubuntu node
  include puppet_infrastructure::node_base
  # Install nginx and perform configurations common to all servers
  include puppet_infrastructure::nginx_base
  # Open ports for http and https
  firewall { '200 nginx http': proto => 'tcp', dport => 80, action => 'accept', }
  firewall { '210 nginx https': proto => 'tcp', dport => 443, action => 'accept', }

  # This class creates these servers:
  # - http server that redirects to https
  # - http_www server that redirects to https_www
  # - default server that redirects to https_www when accessed by IP
  # - http monitoring server
  # - main https server that serves https requests with and without www
  # This class also prevents redirects to external URLs. Since the nginx_frontend class manages ssl by default, it expects the ssl certificates and private key to be installed.
  # In this example those certificates should be multidomain and include mail.example.com and chat.example.com because the defined types for mail.example.com and chat.example.com (the 2 examples below this one) don't manage ssl.
  class { 'puppet_infrastructure::nginx_frontend':
    domain                       => 'example.com',
    frontend_sslprefix           => 'example.com',
    backend_hosts_and_ports      => ['127.0.0.1:8000', ],
    backend_protocol             => 'http',
    redirects_external_prevented => true,
    redirect_default             => true,
    server_monitoring_create     => true,
  }

  # This defined type creates these servers:
  # - http server that redirects to https
  # - main https server that serves http requests without www
  # Doesn't manage ssl, should have a multidomain certificate in the class.
  puppet_infrastructure::nginx_frontend_domain { 'mail.example.com':
    domain                                => 'mail.example.com',
    frontend_sslprefix                    => 'example.com',
    backend_hosts_and_ports               => ['127.0.0.1:8001', ],
    backend_protocol                      => 'http',
    redirect_http_www_to_https_www_create => false,
    server_https_www_create               => false,
  }

  # This defined type creates these servers:
  # - http server that redirects to https
  # - main https server that serves http requests without www
  # The servers only allow access to clients with IPs between 192.168.1.10 and 192.168.1.50
  # Doesn't manage ssl, should have a multidomain certificate in the class.
  puppet_infrastructure::nginx_frontend_domain { 'chat.example.com':
    domain                                => 'chat.example.com',
    frontend_sslprefix                    => 'example.com',
    backend_hosts_and_ports               => ['127.0.0.1:8002', ],
    backend_protocol                      => 'http',
    redirect_http_www_to_https_www_create => false,
    server_https_www_create               => false,
    ip_whitelist                          => [
      '192.168.1.10/31',
      '192.168.1.12/30',
      '192.168.1.16/28',
      '192.168.1.32/28',
      '192.168.1.48/31',
      '192.168.1.50/32',
    ],
  }

  # This defined type creates these servers for a different domain:
  # - http server that redirects to https with www
  # - http www server that redirects to https with www
  # - https server that redirects to https with www
  # - main https server that serves http requests with www
  # It also manages its own ssl certificates and key, they are expected to be found at /etc/puppetlabs/puppet/extra_files/ssl/
  puppet_infrastructure::nginx_frontend_domain { 'example.co.uk':
    domain                  => 'example.co.uk',
    frontend_sslprefix      => 'example.co.uk',
    backend_hosts_and_ports => ['127.0.0.1:8010', ],
    backend_protocol        => 'http',
    decorate_naked          => true,
    manage_ssl              => true,
  }

  # This defined type creates these servers for a different domain:
  # - http server that redirects to https without www
  # - http www server that redirects to https www
  # - main https server that serves http requests with and without www
  # It also manages its own ssl certificates and key, they are expected to be found at /etc/puppetlabs/puppet/extra_files/ssl/
  puppet_infrastructure::nginx_frontend_domain { 'example.net':
    domain                                => 'example.net',
    frontend_sslprefix                    => 'example.net',
    backend_hosts_and_ports               => ['127.0.0.1:8020', ],
    backend_protocol                      => 'http',
    redirect_http_www_to_https_www_create => true,
    server_https_www_create               => true,
    manage_ssl                            => true,
  }

}

This example has 1 domain, example.com with 2 subdomains, mail.example.com and chat.example.com, and 2 other domains, example.co.uk and example.net.

You can find a similar example here: https://bitbucket.org/asolidodev/puppet_infrastructure/src/stable/node-examples/nginx-frontend/nginx-frontend03.pp