This terraform module is used to provision an opensearch cluster on machines with libvirt/qemu/kvm.
It assumes that pki authentication will be used (both for node to node communication and for client to server authentication, with optional basic auth authentication supported on the client side) and that most settings not required to bootstrap the cluster (users, roles, tenants, etc) will be generated separately using the opensearch api.
It also assumes that there will two types of nodes in your cluster: Dedicated managers and dedicated workers.
This terraform module has been validated on recent ubuntu images. Your mileage may vary with other distributions.
This module also supports pre-built images. See the following for the expectations about the images: https://github.com/Ferlab-Ste-Justine/vm-image-builds/blob/main/builds/kvm-opensearch/ansible/playbook.yml
- name: Name to give to the vm. Will be the hostname and name to identity the node in the opensearch cluster as well.
- vcpus: Number of vcpus to assign to the vm. Defaults to 2.
- memory: Amount of memory in MiB to assign to the vm. Defaults to 8192.
- volume_id: Id of the image volume to attach to the vm. Can either be a base os image or a pre-built image with dependencies pre-installed.
- libvirt_network: Parameters to connect to a libvirt network if you opt for that instead of macvtap interfaces. In has the following keys:
- ip: Ip of the vm.
- mac: Mac address of the vm. If none is passed, a random one will be generated.
- network_id: Id (ie, uuid) of the libvirt network to connect to.
- macvtap_interfaces: List of macvtap interfaces to connect the vm to if you opt for macvtap interfaces instead of a libvirt network. Note that opensearch will only bind on and listen on the first mapvtap interface of the list. Each entry in the list is a map with the following keys:
- interface: Host network interface that you plan to connect your macvtap interface with.
- prefix_length: Length of the network prefix for the network the interface will be connected to. For a 192.168.1.0/24 for example, this would be 24.
- ip: Ip associated with the macvtap interface.
- mac: Mac address associated with the macvtap interface
- gateway: Ip of the network's gateway for the network the interface will be connected to.
- dns_servers: Dns servers for the network the interface will be connected to. If there aren't dns servers setup for the network your vm will connect to, the ip of external dns servers accessible accessible from the network will work as well.
- cloud_init_volume_pool: Name of the volume pool that will contain the cloud-init volume of the vm.
- cloud_init_volume_name: Name of the cloud-init volume that will be generated by the module for your vm. If left empty, it will default to -cloud-init.iso.
- ssh_admin_user: Username of the default sudo user in the image. Defaults to ubuntu.
- admin_user_password: Optional password for the default sudo user of the image. Note that this will not enable ssh password connections, but it will allow you to log into the vm from the host using the virsh console command.
- ssh_admin_public_key: Public part of the ssh key the admin will be able to login as
- chrony: Optional chrony configuration for when you need a more fine-grained ntp setup on your vm. It is an object with the following fields:
- enabled: If set the false (the default), chrony will not be installed and the vm ntp settings will be left to default.
- servers: List of ntp servers to sync from with each entry containing two properties, url and options (see: https://chrony.tuxfamily.org/doc/4.2/chrony.conf.html#server)
- pools: A list of ntp server pools to sync from with each entry containing two properties, url and options (see: https://chrony.tuxfamily.org/doc/4.2/chrony.conf.html#pool)
- makestep: An object containing remedial instructions if the clock of the vm is significantly out of sync at startup. It is an object containing two properties, threshold and limit (see: https://chrony.tuxfamily.org/doc/4.2/chrony.conf.html#makestep)
- fluentd: Optional fluend configuration to securely route logs to a fluend node using the forward plugin. It has the following keys:
- enabled: If set the false (the default), fluentd will not be installed.
- opensearch_tag: Tag to assign to logs coming from opensearch
- node_exporter_tag Tag to assign to logs coming from the prometheus node exporter
- forward: Configuration for the forward plugin that will talk to the external fluend node. It has the following keys:
- domain: Ip or domain name of the remote fluend node.
- port: Port the remote fluend node listens on
- hostname: Unique hostname identifier for the vm
- shared_key: Secret shared key with the remote fluentd node to authentify the client
- ca_cert: CA certificate that signed the remote fluentd node's server certificate (used to authentify it)
- buffer: Configuration for the buffering of outgoing fluentd traffic
- customized: Set to false to use the default buffering configurations. If you wish to customize it, set this to true.
- custom_value: Custom buffering configuration to provide that will override the default one. Should be valid fluentd configuration syntax, including the opening and closing
<buffer>tags.
- opensearch: Opensearch configuration. It has the following keys:
- cluster_name: Name of the opensearch cluster. Should be the same for all members of the cluster.
- manager: Whether the ndoe should be a dedicated manager node (otherwise it will be a dedicated worker node).
- seed_hosts: List of manager nodes that the nodes should synchronize to in order to join the cluster. Should be ips or domain names.
- bootstrap_security: Whether the node should bootstrap opensearch security. One and only one node should have this flag set to true when the opensearch cluster is initially created.
- initial_cluster: Whether this node is created as part of the initial cluster that will form opensearch. Nodes that are added to the cluster afterwards should set this to false.
- tls: Parameters to setup tls certificates for networking traffic between cluster members and with clients. It takes the following keys:
- ca_certificate: Certificate of the CA used to sign all other certificates (both for the servers and clients)
- server: Tls credentials for the opensearch nodes
- key: Private tls key
- certificate: Public tls certificate
- admin_client: Tls credentials for an admin client
- key: Private tls key
- certificate: Public tls certificate
- auth_dn_fields: Fields in the certificates that will be used to authentify the admin client and other nodes. Should be the same for all nodes. It is expected to have the following keys:
- admin_common_name: CN value that will identity/authentify the admin user in the admin's client certificate.
- node_common_name: CN value that will identity/authentify this node and other nodes during node-to-node communication.
- organization: Organization value (in the certificat's subject) that will also be used to identify/authentify the admin client and other nodes.
- verify_domains: Whether the domain information in the node certificates should be verified to see if it corresponds to the nodes (that is additional validation on top of the CN validation).
- basic_auth_enabled: Whether basic auth should be enabled as an alternate to certificate authentication as a way to login.
- install_dependencies: Whether cloud-init should install external dependencies (should be set to false if you already provide an image with the external dependencies built-in).