foreman_deployments 0.0.1

data/doc/design/resources.md

@@ -0,0 +1,134 @@
+## Configuration resources
+
+![Configuration resource class diagram](./diagrams/config_resource_overview.png)
+[SVG version of the diagram for better readability](./diagrams/config_resource_overview.svg)
+
+#### Host
+Define host roles, for example "Database" or "Proxy".
+
+* enables to specify a range for the number of hosts of such type
+* each host is required to be in a hostgroup
+* hosts are named "#{name}-#{index}", hosts created without provisioning keep their original name
+* relationships:
+  * belongs to `hostgroup resource` - each host needs to be in a hostgroup, deployment always creates a new one
+  * has many `puppet_run resources`, `subnet_type resources`
+* user input:
+  * number of such hosts from the range
+  * selecting existing hosts or compute resource and it's parameters
+  * networking setup for the hosts
+  * whether to provision the host or not
+
+#### Hostgroup
+Defines hostgroup that will be created and used internally for organizing the hosts in a deployment.
+
+* users can select a parent hostgroup to inject OS settings, puppet proxies and others
+* parents can be defined also in the stack as another hostgroup resource
+* relationships:
+  * belongs to `hostgroup resource` - for means of the hostgroup's resource inheritance
+  * has many `parameter resources`, `host resources`, `puppetclass resources`
+* user input:
+  * parent hostgroup
+
+#### SubnetType
+Declares what subnet types are used in the stack, for example "Public API subnet" and "Provisioning subnet". There will always be at least one subnet type for the provisioning purposes. Host resource selects what subnet types it uses. Hosts are required to have one NIC per subnet type.
+
+* relationships:
+  * has many `host resources`
+* user input:
+  * select subnet from the foreman
+
+#### Interface
+Dummy interface that is not assigned to any host. It's purpose is to reserve address from the subnet's range.
+
+* relationships:
+  * belongs to `subnet_type resource`
+
+**FUTURE FEATURE**: *it might be interesting to define interfaces requirements on hosts too, e.g. HA deployment requires bond of 2 physical interfaces*
+
+#### HostgroupParameter
+Stack's input parameters that are set on a hostgroup. They allow using erb snippets in the value as usual parameters in the Foreman do.
+They are one of the main entry points for user's input. When configured they set global parameter for the hostgroup.
+
+* parameters can have default value
+* if the parameter is already set in the parent, we ignore setting it (requires explicit 'inherit' value on parameter)
+* they bear a flag telling if it should be or shouldn't be configured by users
+
+* relationships:
+  * belongs to `hostgroup resource`
+* user input:
+  * parameter value
+
+#### StackParameter (nice to have, future feature)
+Global parameters for the whole stack (having the same features as `HostgroupParameter`s). When configured they are copied to all hostgroups as global parameters
+unless the hostgroup already defines such parameter.
+
+* user input:
+  * parameter value
+
+#### PuppetClass
+Puppet classes to be assigned to a hostgroup. It is user's esponsibility to make sure the class is present in the selected environment. We will validate their presence
+in the `before_deployment_validation`. The resource contains meta-parameters with the link to sources and version to point where the class comes from when it's missing.
+
+* relationships:
+  * belongs to `hostgroup resource`
+* user input:
+  * NONE
+
+#### PuppetClassOverride
+Allows setting override values for a puppet class on a hostgroup.
+
+* relationships:
+  * belongs to `puppet class resource`
+* user input:
+  * NONE
+
+#### ComputeResourceType
+Puts restriction on where the host can be deployed and what are the minimal requirements. For example we can require a specific image for EC2 compute-resource.
+
+* relationships:
+  * belongs to `hostgroup resource`
+* user input:
+  * NONE
+
+#### ConnectParameter
+ConnectParameter simplifies connecting parameters from parent and child stacks. It only propagates value from a parameter to a parameter of the child stack.
+
+
+
+## Ordered resources
+
+![Ordered resource class diagram](./diagrams/ordered_resource_overview.png)
+[SVG version of the diagram for better readability](./diagrams/ordered_resource_overview.svg)
+
+#### PuppetRun
+Triggers a puppetrun on a host.
+
+* relationships:
+  * belongs to `host resource`
+* user input:
+  * NONE
+
+#### ParameterUpdate
+Updates a parameter on a hostgroup.
+
+* relationships:
+  * belongs to `parameter resource`
+* user input:
+  * NONE
+
+
+#### ChildStack
+Executes another stack.
+
+* user input:
+  * NONE
+
+
+#### RemoteExecution
+Execute custom code on a host.
+
+* relationships:
+  * belongs to `host resource`
+* user input:
+  * NONE
+

data/doc/design/sat_stack.puml

@@ -0,0 +1,37 @@
+@startuml
+
+object ProvisioningSubnet <<TakeSubnet>> {
+
+}
+
+object SatelliteOs <<TakeOs>> {
+  description: OS for the Satellite machine
+  family: RHEL
+  version: '>= 6.5'
+}
+
+object SatelliteMachine <<TakeHost>> {
+  count: 1
+  name: <input>
+  subnet: <reference to ProvisioningSubnet>
+  os: <reference to SatelliteOs>
+  activation_key: <input>
+}
+
+object ProvisionSatellite <<ProvisionHost>> {
+  host: <reference to SatelliteMachine>
+}
+
+object InstallSatellite <<RemoteExecution>> {
+  host: <reference to SatelliteMachine>
+  command: "katello-installer ..."
+  parameters: [password, ...]
+}
+
+
+ProvisioningSubnet -[#gray]-> SatelliteMachine
+SatelliteOs -[#gray]-> SatelliteMachine
+SatelliteMachine -[#gray]-> ProvisionSatellite
+ProvisionSatellite -[#gray]-> InstallSatellite
+
+@enduml

data/doc/design/shared.puml

@@ -0,0 +1,171 @@
+!define DEPLOYCOLOR DarkGreen
+!define FOREMANCOLOR DarkOrange
+!define CONNECTIONCOLOR DarkBlue
+!define FOREMAN << (C,FOREMANCOLOR) Foreman >>
+!define ORDERED << (C,green) Ordered >>
+!define FONT skinparam defaultFontName "Helvetica Neue"
+!define OBJECT(name,klass) object name <<klass>>
+!define DEPLOYOBJECT(type) skinparam objectBorderColor<<type>> DEPLOYCOLOR
+!define FOREMANOBJECT(type) skinparam objectBorderColor<<type>> FOREMANCOLOR
+
+!definelong CONFIGRESOURCES
+
+
+class HostgroupResource {
+    String name
+    .. notes ..
+    Parent is HostgroupResource
+    or it's provided on Deployment
+    configuration.
+}
+
+class ParameterResource {
+    String name
+    String description # intent
+    String default_value # optional
+    .. notes ..
+    Validations, like list of allowed
+    values.
+}
+
+class HostgroupParameterResource {
+    .. notes ..
+    Turns into GroupParameter.
+}
+
+class DeploymentParameterResource {
+    .. notes ..
+    Turns into DeploymentParameter.
+}
+
+class ParameterOverrideResource {
+    String key
+    String value # optional, ERB
+    .. notes ..
+    If value is not present it
+    needs to be supplied on
+    deployment configuration.
+}
+
+class ComputeResourceResource {
+    String type
+    Boolean image_based
+    String image_url nullable
+    .. notes ..
+    Each ComputeResourceResource allows
+    particular ComputeResource type for
+    a given HostResource. It has to
+    contain image_url when image_based.
+}
+
+class PuppetClassResource {
+    String name
+    \# of the class to add
+    .. notes ..
+    possibly allot to limit
+    puppet class versions
+}
+
+class SubnetTypeResource {
+    String name
+    .. notes ..
+    like Staypuft
+    network types
+}
+
+class InterfaceResource {
+    String ip
+    .. notes ..
+    creates interface without
+    Host to reserve IP
+}
+
+class HostResource {
+    String name # "db-%02d"
+    Integere min
+    Integere max
+}
+
+class ConnectParameterResource {
+    .. notes ..
+    Possibly allow to define
+    a transformation function.
+    Only resource allowing to connect
+    resources form child stacks.
+    ERB is inserted to destination
+    to propagate value from source.
+}
+
+InterfaceResource "0..*" --> "1" SubnetTypeResource : where
+HostgroupParameterResource "0..*" --> "0..1" HostgroupResource : will be\nadded to
+ParameterOverrideResource "0..*" --> "1" PuppetClassResource : overrides\nin
+PuppetClassResource "0..*" --> "1" HostgroupResource : will be\nadded to
+HostResource "0..*" --> "0..*" SubnetTypeResource : connects to
+HostResource "1..*" --> "1..*" ComputeResourceResource : allowed ComputeResources
+ConnectParameterResource "0..*" --> "1" ParameterResource : source
+ConnectParameterResource "0..1" --> "1" ParameterResource : destination
+HostResource "0..*" --> "1" HostgroupResource : provisions in
+HostgroupResource "0..*" <-- "0..1" HostgroupResource : be parent of
+note on link
+    Foreign keys cannot be stored on
+    target HostgroupResource.
+    It would prevent Stack share-ability.
+end note
+
+
+Resource <|-[#gray]- HostgroupResource
+Resource <|-[#gray]- HostResource
+Resource <|-[#gray]- ParameterResource
+ParameterResource <|-[#gray]- HostgroupParameterResource
+ParameterResource <|-[#gray]- DeploymentParameterResource
+Resource <|-[#gray]- ParameterOverrideResource
+Resource <|-[#gray]- PuppetClassResource
+Resource <|-[#gray]- ComputeResourceResource
+Resource <|-[#gray]- SubnetTypeResource
+Resource <|-[#gray]- InterfaceResource
+Resource <|-[#gray]- ConnectParameterResource
+
+!enddefinelong
+
+
+
+!definelong ORDEREDRESOURCES
+
+
+abstract class Resource {
+    .. notes ..
+    A Foreman object to be configured or created
+    to form an Deployment instance.
+}
+
+abstract class Ordered <<(A,orchid)>> {
+    .. notes ..
+    Resources that are ordered and executed via dynflow.
+}
+
+class ChildStackResource ORDERED
+
+class ParameterUpdateResource ORDERED {
+    Staring value
+    .. notes ..
+    possibly ERB to compute new value
+}
+
+class PuppetRunResource ORDERED
+
+class RemoteExecutionResource ORDERED
+
+Resource <|-[#gray]-- Ordered
+
+Ordered <|-[#gray]- ChildStackResource
+Ordered <|-[#gray]- ParameterUpdateResource
+Ordered <|-[#gray]- PuppetRunResource
+Ordered <|-[#gray]- RemoteExecutionResource
+
+PuppetRunResource "0..*" --> "1" HostResource : on
+RemoteExecutionResource "0..*" --> "1" HostResource : on
+ParameterUpdateResource "0..*" --> "1" ParameterResource : updates
+
+!enddefinelong
+
+

data/doc/design/solr_usecase.puml

@@ -0,0 +1,189 @@
+@startuml
+
+title Solr stack
+scale 3500 width
+
+!include shared.puml
+FONT
+
+package zookeeper_server_stack {
+  object zk_machine_restrictions <<MachineRestrictionsResource>>{
+    CPU = 1
+    memory = 4GB
+    NOTE:
+    This resource is not part of the current design.
+    The machine requirements can be solved multiple
+    ways.
+  }
+
+  object zk_id <<ParamResource>> {
+    name = 'id'
+    value = "<%= @host.id %>"
+  }
+
+  object zk_ring <<ParamResource>> {
+    name = 'servers'
+    value = []
+  }
+
+  object zk_client_ip <<ParamResource>> {
+    name = 'zk_client_ip'
+    value = "$::ipaddress_eth0"
+  }
+
+
+  object zk_server <<HostgroupResource>> {
+  }
+
+  object zk_server_instance <<HostResource>> {
+    count = 4
+  }
+
+
+  object zk_subnet <<SybnetTypeResource>> {
+    name = 'provisioning'
+  }
+
+  object zk_server_instance_run <<PuppetRunResource>> {
+  }
+
+  object zk_zookeeper_class <<PuppetclassResource>> {
+    name = 'zookeeper'
+    source = https://github.com/deric/puppet-zookeeper
+    client_ip => $::ipaddress_eth0
+  }
+
+  object zk_install_java_params <<ParamResource>> {
+    name = 'install_java'
+    value = 'true'
+  }
+
+  object zk_java_pacakge_params <<ParamResource>> {
+    name = 'java_package'
+    value = 'openjdk-7-jre-headless'
+  }
+
+  zk_server_instance <-- zk_server
+  zk_server <-- zk_zookeeper_class
+  zk_server <-- zk_id
+  zk_server <-- zk_ring
+  zk_server <-- zk_client_ip
+  zk_server <-- zk_install_java_params
+  zk_server <-- zk_java_pacakge_params
+  zk_server_instance <-- zk_machine_restrictions
+  zk_server_instance <-- zk_server_instance_run
+  zk_server_instance <-- zk_subnet
+}
+
+
+package solr_single_shard_stack {
+
+  object solr_machine <<MachineRestrictionsResource>>{
+    CPU = 4
+    memory = 16GB
+    NOTE:
+    This resource is not part of the current design.
+    The machine requirements can be solved multiple
+    ways.
+  }
+
+  object solr_zk_ring <<ParamResource>> {
+    name = 'servers'
+    value =["$::ipaddress_eth0"]
+  }
+
+  object solr_client_fqdn <<ParamResource>> {
+    name = 'client_fqdn'
+    value = '$::fqdn_eth0'
+  }
+
+  object solr_home <<ParamResource>> {
+    name = 'home_folder'
+    value = '/home/lukasz/solr-4.2.1'
+  }
+
+  object solr_server <<HostgroupResource>> {
+  }
+
+  object solr_server_instance <<HostResource>> {
+    count = 1
+  }
+
+  object solr_subnet <<SybnetTypeResource>> {
+    name = 'provisioning'
+  }
+
+  object solr_server_instance_run <<PuppetRunResource>> {
+  }
+
+  object java_class <<PuppetclassResource>> {
+    name = 'puppetlabs-java'
+    source = 'https://github.com/puppetlabs/'
+  }
+  object tomcat_class <<PuppetclassResource>> {
+    name = 'puppetlabs-tomcat'
+    source = 'https://github.com/puppetlabs/puppetlabs-tomcat'
+  }
+  object solr_install_class <<PuppetclassResource>> {
+    name = 'solr-shard'
+    source = 'https://github.com/needs/creating'
+  }
+
+
+  solr_server_instance <-- solr_server
+  solr_server <-- java_class
+  solr_server <-- tomcat_class
+  solr_server <-- solr_install_class
+  solr_server <-- solr_zk_ring
+  solr_server <-- solr_client_fqdn
+  solr_server <-- solr_home
+  solr_server_instance <-- solr_machine
+  solr_server_instance <-- solr_server_instance_run
+  solr_server_instance <-- solr_subnet
+}
+
+
+object zookeeper_childstack <<ChildStackResource>> {
+
+}
+object solr_single_shard_childstack <<ChildStackResource>> {
+
+}
+
+object update_zk_ring_param <<ParamUpdateResource>> {
+  name = 'servers'
+  value = '<%= hosts_in('zk_server').map(&:ip) %>'
+}
+update_zk_ring_param --> zk_ring
+
+object update_solr_zk_ring_param <<ParamUpdateResource>> {
+  name = 'servers'
+  value = '<%= hosts_in('zk_server').map(&:ip) %>'
+}
+update_solr_zk_ring_param --> solr_zk_ring
+
+object zk_server_instance_run2 <<PuppetRunResource>> {
+  NOTE
+  Scond run to propagate the updated parameters
+}
+zk_server_instance_run2 --> zk_server_instance
+
+object solr_server_instance_run2 <<PuppetRunResource>> {
+  NOTE
+  Scond run to propagate the updated parameters
+}
+solr_server_instance_run2 --> solr_server_instance
+
+
+zookeeper_childstack <-- zookeeper_server_stack
+solr_single_shard_childstack <-- solr_single_shard_stack
+
+zookeeper_childstack <-[#gray]- update_zk_ring_param : depends on
+solr_single_shard_childstack <-[#gray]- update_zk_ring_param : depends on
+
+update_zk_ring_param <-[#gray]- update_solr_zk_ring_param : depends on
+
+update_solr_zk_ring_param <-[#gray]- zk_server_instance_run2 : depends on
+update_solr_zk_ring_param <-[#gray]- solr_server_instance_run2 : depends on
+
+@enduml