updated README

neo-technology · Mar 15, 2024 · beccf27 · beccf27
1 parent b30f6cb
commit beccf27
Show file tree

Hide file tree

Showing 2 changed files with 36 additions and 15 deletions.
diff --git a/README.md b/README.md
@@ -1,19 +1,22 @@
 
 **AWS Ec2 Auto-scaling-group Discovery plugin for Neo4j**
 
-This neo4j plugin implements cluster discovery for a cluster deployed in an AWS EC2 Auto-scaling group. 
-It retrieves the list of network addresses of the group's VMs, and feeds it to Neo4j's cluster discovery module.
+This neo4j plugin implements cluster discovery for a cluster deployed on AWS EC2 VMs.
+It retrieves the list of network addresses of the VMs in a neo4j cluster, and feeds it to Neo4j's cluster discovery module.
+The VMs can be found by :
+- The name of the AutoScaling Group they belong to
+- a Tag
 
 Notes:
-- It retrieves the VMs' private DnsName or IpAddress.
-- It retrieves the discovery TCP port from the neo4j setting "server.discovery.listen_address"
+- VMs must be running
+- the retrieved network address can be one of: private DnsName, public DnsName, private IpAddress or public IpAddress.
+- the discovery TCP port is extracted from the neo4j setting "server.discovery.listen_address" (or the default port is used otherwise)
 
 
 **Compatilibity**
 
-Neo4j 5.7+
+Neo4j 5.18+
 
-Note: there could be changes to the plugin API.
 
 **Usage**
 
@@ -23,20 +26,20 @@ Note: there could be changes to the plugin API.
 
 **Settings**
 
-- `dbms.cluster.discovery.resolver_type=EC2-ASG`   : select the discovery protocol implemented by this plugin
+- `dbms.cluster.discovery.resolver_type=EC2`   : select the discovery protocol implemented by this plugin
 - `server.config.strict_validation.enabled=false`  : to disable strict settings validation, which will allow the usage of the following plugin-specific settings (You may still get Warnings : "Unrecognized setting").
-- `dbms.cluster.discovery.aws.asg_name=<asg_name>` : the name of the Auto-scaling group
 
+One of the following to specify how to find the VMs:
+- `dbms.cluster.discovery.aws.asg_name=<asg_name>` : the name of the Auto-scaling group which contains the VMs. Takes precedence over "vm_tag".
+- `dbms.cluster.discovery.aws.vm_tag`              : VM tag in the format "tagKey:value" (ex: `dbms.cluster.discovery.aws.vm_tag=cluster:neo4jprod`). Ignored if "asg_name" is set.
 
 Optionally :
-- `dbms.cluster.discovery.aws.region=<region>`     : the AWS region hosting the Auto-scaling group (ex: "eu-west-1")
-
-If not set, the plugin will attempt to retrieve the region from the VM metadata
+- `dbms.cluster.discovery.aws.region=<region>`     : the AWS region hosting the Auto-scaling group (ex: "eu-west-1"). If not set, the plugin will attempt to retrieve the region from the VM metadata
 
 - `dbms.cluster.discovery.aws.key=<key>`           : the Access Key of the user connecting to the AWS API.
 - `dbms.cluster.discovery.aws.secret=<secret>`     : the Secret Key of the user connecting to the AWS API.
 
-If not set, the plugin will try to use any InstanceProfile role attached to the EC2 instance. That can be defined in the ASG's LaunchTemplate.
+  If key/secret are not set, the plugin will try to use any InstanceProfile role attached to the EC2 instance. See below for required permissions. That can be defined in the ASG's LaunchTemplate.
 
 - `dbms.cluster.discovery.aws.address_type=<type>` : type of network address to retrieve from the VM, to use for discovery. One of PRIVATE_IP|PRIVATE_DNSNAME|PUBLIC_IP|PUBLIC_DNSNAME. Defaults to PRIVATE_IP. Must match the type of `server.discovery.advertised_address`.
 
@@ -47,5 +50,3 @@ If not set, the plugin will try to use any InstanceProfile role attached to the
 - The Role/User requires the following permissions :
   - "ec2:DescribeInstances",
   - "autoscaling:DescribeAutoScalingGroups"
-
-- The auto-scaling group VMs require a Security Group that allows traffic on TCP ports 5000, 6000, 7000, 7688 (for internal cluster communication) as well as TCP ports 7474 and 7687 (for external access).
diff --git a/cloudformation/neo4j.template.yaml b/cloudformation/neo4j.template.yaml
@@ -469,6 +469,10 @@ Resources:
             - Ref: AWS::Region
             - "\n"
 
+            - "diskSize="
+            - Ref: DiskSize
+            - "\n"
+
             - "install_neo4j_from_yum() {\n"
             - "  echo \"Installing Graph Database...\"\n"
             - "  export NEO4J_ACCEPT_LICENSE_AGREEMENT=yes\n"
@@ -550,7 +554,7 @@ Resources:
             - "    sed -i s/#initial.dbms.default_secondaries_count=0/initial.dbms.default_secondaries_count=$(expr ${nodeCount} - 3)/g /etc/neo4j/neo4j.conf\n"
             - "    sed -i s/#server.bolt.listen_address=:7687/server.bolt.listen_address=\"${privateIP}\":7687/g /etc/neo4j/neo4j.conf\n"
             - "    echo \"dbms.cluster.minimum_initial_system_primaries_count=${nodeCount}\" >> /etc/neo4j/neo4j.conf\n"
-            - "    echo \"dbms.cluster.discovery.resolver_type=EC2-ASG\" >> /etc/neo4j/neo4j.conf\n"
+            - "    echo \"dbms.cluster.discovery.resolver_type=EC2\" >> /etc/neo4j/neo4j.conf\n"
             - "    echo \"dbms.cluster.discovery.aws.asg_name=$stackName\" >> /etc/neo4j/neo4j.conf\n"
             - "    echo \"initial.dbms.automatically_enable_free_servers=true\" >> /etc/neo4j/neo4j.conf\n"
             - "  fi\n"
@@ -595,6 +599,20 @@ Resources:
             - "  done\n"
             - "}\n"
 
+            - "attach_volume() {\n"
+            - "  echo \"Attaching disk volume...\"\n"
+            - "  TOKEN=`curl -s -X PUT \"http://169.254.169.254/latest/api/token\" -H \"X-aws-ec2-metadata-token-ttl-seconds: 21600\"`\n"
+            - "  AZ=`curl -H \"X-aws-ec2-metadata-token: $TOKEN\" -v http://169.254.169.254/latest/meta-data/placement/availability-zone`\n"
+            - "  instance_id=`curl -H \"X-aws-ec2-metadata-token: $TOKEN\" -v http://169.254.169.254/latest/meta-data/placement/instance-id`\n"
+            - "  echo \"Current VM is ${instance_id} in AZ ${AZ}.\"\n"
+            - "  volume_id=$(aws ec2 describe-volumes --region \"${region}\" --filters Name=availability-zone,Values=$AZ Name=status,Values=available Name=size,Values=$diskSize |jq '.Volumes[0].VolumeId')\n"
+            - "  echo \"TODO : add filter on tag Name=tag:XX,Values=YY \"\n"
+            - "  if [[ -n $volume_id ]]; then\n"
+            - "    echo \"Found available volume ${volume_id} in AZ ${AZ} with size ${$diskSize}g. \"\n"
+            - "    aws ec2 attach-volume --region \"${region}\" --volume $volume_id --instance $instance_id --device \"/dev/xvda\" \n"
+            - "  fi\n"
+            - "}\n"
+
             - "tag_asg_with_neo4j_version() {\n"
             - "  if [[ -z $NEO4J_VERSION_ASG_TAG ]]; then\n"
             - "    echo \"Tagging AutoScalingGroup $ASG_NAME with Key NEO4J_VERSION and Value $PACKAGE_VERSION\"\n"
@@ -617,6 +635,7 @@ Resources:
             - "configure_graph_data_science\n"
             - "configure_bloom\n"
             - "add_cypher_ip_blocklist\n"
+            - "#attach_volume\n"
             - "start_neo4j\n"
             - "tag_asg_with_neo4j_version\n"
 
@@ -649,6 +668,7 @@ Resources:
                   - autoscaling:DescribeAutoScalingGroups
                   - cloudformation:DescribeStack*
                   - ec2:DescribeInstances
+                  - ec2:DescribeVolumes
                 Resource: "*"
 
   Neo4jExternalSecurityGroup: