Better documentation for EC2 securityGroups and securityGroupIds

[Niklas Hambüchen]

Right now we have:

    deployment.ec2.securityGroups = mkOption {
      default = [ "default" ];
      example = [ "my-group" "my-other-group" ];
      type = types.listOf (types.either types.str (resource "ec2-security-group"));
      apply = map (x: if builtins.isString x then x else x.name);
      description = ''
        Security groups for the instance.  These determine the
        firewall rules applied to the instance.
      '';
    };

    deployment.ec2.securityGroupIds = mkOption {
      default = [ "default" ];
      type = types.listOf types.str;
      description = ''
        Security Group IDs for the instance. Necessary if starting
        an instance inside a VPC/subnet. In the non-default VPC, security
        groups needs to be specified by ID and not name.
      '';
    };

This is hard to understand. In which cases should I used securityGroups, and in which securityGroupIds?

• The docs of the latter say Necessary if starting an instance inside a VPC/subnet but that seems wrong: Using securityGroups = ["nixops"] after having declared a resources.ec2SecurityGroups."nixops".name = "nixops" works.
• If I do deployment.ec2.securityGroupIds = ["nixops"] or even ["garbage"], then it uses the default security group instead of complaining. Is that intended?
• We should add some examples, ideally also one that shows how to use the type resource "ec2-security-group" approach, referring to a resources.ec2SecurityGroups. And also an example to make super clear that securityGroupIds should probably start with sg-.

[Ryan Lahfa]

Hi, I agree, I had some problems with this, the key is:

• securityGroups are for non-VPC instances.
• securityGroupIds are for VPC instances.

If you don't attach a VPC, you won't see the issue. Once a VPC is attached, securityGroups will cease to work, you'll have to use securityGroupIds with a properly referenced resource or ID.

For example: deployment.ec2.securityGroupIds = [ resources.ec2SecurityGroups.some-group ] is the approach where you use the resource type, it'll automatically put the sg-stuff for you.

I think there are examples in the repo, but those are not enough put in the website docs alas.