დასახელების კონვენცია

ზოგადი კონვენცია

არ არსებობს მიზეზი იმისა თუ რატომ არ უნდა გაყვეთ ამ დასახელების კონვენციას :)

გაითვალისწინეთ რომ ღრუბლოვან რესურსებს (cloud resources) ხშირად აქვთ აკრძალვები დაშვებულ სახელებში. ზოგიერთი რესურსს მაგალითად არ შეუძლია შეიცავდეს - ს. ამ წიგნში მოყვანილი კონვენციები თავისთავად ეხება Terraform სახელებს.

1. გამოიყენეთ _ (underscore) - (dash) მაგიერ ყველგან (რესურსების დასახელებაში, მონაცემთა წყაროს სახელებში, ცვლადების სახელეში და ა.შ.).

2. უკეთესია გამოიყენოთ lowercase ასოები და ციფრები (მიუხედავად UTF-8 მხარდაჭერისა).

რესურსისა და მონახემთა წყაროების არგუმენტები

1. ნუ გამოიყენებთ რესურსის ტიპს რესურსის სახელში (ნაწილობრივ თუ სრულად):

`resource "aws_route_table" "public" {}`

`resource "aws_route_table" "public_route_table" {}`

`resource "aws_route_table" "public_aws_route_table" {}`

1. რესურსის სახელს უნდა ერქვას this იმ შემთხვევაში თუ არ არის მეტი აღწერითი და ზოგადი სახელი ხელმისაწვდომი, ან თუ რესურსის მოდული ქმნის მხოლოდ ერთ ასეთი ტიპის რესურსს (მაგალითად, AWS VPC module -ში არის მხოლოდ ერთი aws_nat_gateway ტიპის რესურსი და რამოდენიმე typeaws_route_table ტიპის რესურსი, ამიტომ aws_nat_gateway -ს უნდა დაერქვას this და aws_route_table -ს უნდა ჰქონდეს მეტი აღწერითი სახელები - როგორიცაა private, public, database).

2. დასახელებებში ყოველთვის გამოიყენეთ მხოლობითი არსებითი სახელები.

3. გამოიყენეთ - არგუმენტების მნიშვნელობებსა და იმ ადგილებში სადაც ეს მნიშვნელობები იქნება გამოტანილი საჯაროდ (მაგალითად, RDS instance-ის DNS სახელში).

4. გამოიყენე არგუმენტი nclude argument count / for_each რესურსში ან მონაცემთა წყაროს ბლოკში პირველ არგუმენტად დასაწყისში და გამოყავით ახალი ხაზით.

5. გამოიყენეთ არგუმენტი tags, თუ რესურსს აქვს ამის მხარდაჭერა, depends_on და lifecycle ბლოკებამდე, თუ არსებობს ამის საჭიროება. ყველა ბლოკი უნდა გამოიყოს ცარიელი ხაზით.

6. count / for_each არგუმენტებში კონდიციების გამოყენებისას, უპირატესობა მიანიჭეთ boolean მნიშვნელობს ვიდრე length ან სხვა ტიპის expression-ებს.

რესურსის(resource) კოდის მაგალითები

count / for_eachU-ის გამოყენება

main.tf

resource "aws_route_table" "public" {
  count = 2

  vpc_id = "vpc-12345678"
  # ... remaining arguments omitted
}

resource "aws_route_table" "private" {
  for_each = toset(["one", "two"])

  vpc_id = "vpc-12345678"
  # ... remaining arguments omitted
}

main.tf

resource "aws_route_table" "public" {
  vpc_id = "vpc-12345678"
  count  = 2

  # ... remaining arguments omitted
}

ტეგების (tags) განთავსება

main.tf

resource "aws_nat_gateway" "this" {
  count = 2

  allocation_id = "..."
  subnet_id     = "..."

  tags = {
    Name = "..."
  }

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }
}   

main.tf

resource "aws_nat_gateway" "this" {
  count = 2

  tags = "..."

  depends_on = [aws_internet_gateway.this]

  lifecycle {
    create_before_destroy = true
  }

  allocation_id = "..."
  subnet_id     = "..."
}

კონდიციები count-ში

outputs.tf

resource "aws_nat_gateway" "that" {    # Best
  count = var.create_public_subnets ? 1 : 0
}

resource "aws_nat_gateway" "this" {    # Good
  count = length(var.public_subnets) > 0 ? 1 : 0
}

ცვლადები

1. ნუ გამოიგონებთ ველოსიპედს რესურსის მოდულებში, გამოიყენეთ: name, description, და default მნიშვნელობები ცვლადებისთვის ისე როგორც "Argument Reference" სექციაში არის განსაზღვრული.

2. ცვლადებში ვალიდაციის მხარდაჭერა არის საკმაოდ შეზღუდული (მაგალითად არ აქვს წვდომა სხვა ცვლადებზე). ძირითად შემთხვევბში მიზანშეწონილია გამოიყენოთ Plan-ი, რადგაც ვალიდაციის ოფცია ხშირ შემთხვევაში არის უშედეგო.

3. ცვლადის სახელებში გამოიყენეთ მრავლობითი ფორმა როდესაც მისი ტიპი არის list(...) ან map(...).

4. ცვლადის ბლოკში დაიცავით ელემენტების შემდეგი მიმდევრობა: description , type, default, validation.

5. ყოველთვის გამოიყენეთ description ყველა ცვლადზე (სამომავლოდ აუცილებლად გამოგადგებათ)

6. უმჯობესია გამოიყენოთ მარტივი ცვლადის ტიპები (number, string, list(...), map(...), any) ვიდრე სპეციფიური ტიპები როგორიცაა object() იმ შემთხვევაში თუ არ გჭირდებათ მკაცრი შეზღუდვები key-ებზე.

7. გამოიყენეთ სპეციფიური ცვლადის ტიპები როგორიცაა map(map(string)) იმ შემთხვევაში თუ ყველა ელემენტს map-ზე ერთი და იგივე ცვლადის ტიპი (მაგალითად string) ან შესაძლოა დაკონვერტირდეს მასში (მაგალითად number შესაძლოა დაკონვერტირდეს string-ში).

8. გამოიყენეთ ცვლადის ტიპი any რათა გამოტოვოთ ვალიდაცია როდესაც კონკრეტულ შრეზე ან როდესაც რამოდენიმე ცვლადის ტიპი უნდა იქნას მხარდაჭერილი.

9. მნიშვნელობა(Value) {} ზოგჯერ არის map ტიპისა მაგრამ ხანდახან არის object ტიპის. გამოიყენეთ tomap(...) რათა შექმნა map იმ შემთხვევაში თუ შეზღუდულია object-ის შექმნა.

Outputs

Make outputs consistent and understandable outside of its scope (when a user is using a module it should be obvious what type and attribute of the value it returns).

1. The name of output should describe the property it contains and be less free-form than you would normally want.

2. Good structure for the name of output looks like {name}_{type}_{attribute} , where:

   1. {name} is a resource or data source name without a provider prefix. {name} for aws_subnet is subnet, foraws_vpc it is vpc.

   2. {type} is a type of a resource sources

   3. {attribute} is an attribute returned by the output

   4. See examples.
3. If the output is returning a value with interpolation functions and multiple resources, {name} and {type} there should be as generic as possible (this as prefix should be omitted). See example.
4. If the returned value is a list it should have a plural name. See example.
5. Always include description for all outputs even if you think it is obvious.

6. Avoid setting sensitive argument unless you fully control usage of this output in all places in all modules.

7. Prefer try() (available since Terraform 0.13) over element(concat(...)) (legacy approach for the version before 0.13)

outputკოდის მაგალითი

დააბრუნეთ security group მხოლოდ ერთი ID:

outputs.tf

output "security_group_id" {
  description = "The ID of the security group"
  value       = try(aws_security_group.this[0].id, aws_security_group.name_prefix[0].id, "")
}

ერთი და იმავე ტიპის მრავალი რესურსის არსებობისას, this უნდა იყოს გამოტოვებული Output სახელით:

outputs.tf

output "this_security_group_id" {
  description = "The ID of the security group"
  value       = element(concat(coalescelist(aws_security_group.this.*.id, aws_security_group.web.*.id), [""]), 0)
}

გამოიყენეთ მრავლობითი სახელი, თუ დაბრუნებული მნიშვნელობა არის სია

outputs.tf

output "rds_cluster_instance_endpoints" {
  description = "A list of all cluster instance endpoints"
  value       = aws_rds_cluster_instance.this.*.endpoint
}