راهنمای استفاده از API سرویس DNS

برای استفاده و اعمال تغییرات در پارامترهای محصول DNS ستون (مانند مدیریت رکوردها) می‌توانید یک manifest کوبرنتیز تهیه کنید و سپس آن را با ابزار kubectl (یا هر ابزار دیگری که قابلیت اتصال به API Server کوبرنتیز را دارد)، اعمال کنید.

برای مثال فایل manifest زیر (با فرمت yaml) را در نظر بگیرید:

apiVersion: delivery.cafebazaar.cloud/v1beta1
kind: DomainZone
metadata:
  name: <manifest-name>
  namespace: <your-namespace>
spec:
  email: <email@email.ir>
  origin: <domain.ir>
  records:
    '*':
      - A:
          - 1.2.3.4
          - 5.6.7.8
        geo:
          - country: IR
          - continent: AS
        blockedGeo:
          - country: JP
        ttl: 90
        weight: 1
        hc:
          enabled: true
          protocol: https
          port: 443
          host: hostname
          path: "/uri"
    '@':
      - A:
          - 1.5.9.7
        ttl: 90
    subdomain:
      - TXT: "key=value"
        ttl: 30

JSON

مقادیر apiVersion و kind را مطابق جدول زیر تعیین کنید (رعایت کوچک و بزرگ بودن حروف مهم است):

Value	Type	Field
delivery.cafebazaar.cloud/v1beta1	string	apiVersion
DomainZone	string	kind

در قسمت metadata.name می‌توانید یک نام به resource خود اختصاص دهید. برای اطلاع از کاراکترهای معتبر در نام resource به این لینک مراجعه کنید. در قسمت metadata.namespace هم لازم است که نام namespace خود را وارد کنید.

Value	Type	Metadata
RFC 1123	string	name
RFC 1123	string	namespace

در فیلد spec.origin نام دامنه مبدا را وارد کنید (این نام می‌تواند یک دامنه اصلی یا یک زیردامنه باشد). در فیلد spec.email مقدار ایمیلی را که با آن در پنل اوشن ثبت‌نام کرده‌اید را وارد کنید. در قسمت spec.records لیستی از زیردامنه‌های خود را می‌توانید وارد کنید که هر زیردامنه می‌تواند یک یا چند رکورد DNS داشته باشد. برای اطلاع از جزییات بیشتر نام زیردامنه‌ها و تنظیمات رکوردها به این مستند مراجعه کنید.

Type	spec
string	email
string	origin
object: item: []object	records

فهرست رکوردها

در این قسمت رکوردهایی که توسط سرویس نام دامنه‌ی ستون پشتیبانی می‌شوند و همچنین مقادیری را که این رکوردها می‌توانند داشته باشند، مشاهده می‌کنید. برای اطلاعات بیشتر به این مستند مراجعه کنید.

Example (yaml)	Value Type	Record
A: - 192.168.1.1 - 192.168.1.2 AFallback: - 192.168.1.3	[]string (IPv4)	A \| AFallback
AAAA: - “2400:cb00:2049:1::a29f:1804” - “2400:cb00:2049:1::a29f:1805” AAAAFallback: - “2400:cb00:2049:1::a29f:1806”	[]string (IPv6)	AAAA AAAAFallback
ALIAS: app.domain.ir	string	ALIAS
CNAME: app.domain.ir	string	CNAME
MX: priority: 1 host: mail.domain.ir	object: priority: int host: string	MX
NS: - ns1.domain.ir - ns2.domain.ir	[]string	NS
PTR: “255.2.0.192.in-addr.arpa”	string	PTR
SPF: “v=spf1 ip4:34.243.61.237”	string	SPF
SRV: priority: 1 weight: 1 port: 5060 target: sip.domain.ir	object: priority: int weight: int port: uint16 target: string	SRV
TXT: “key=value”	string	TXT
URI: priority: 1 weight: 1 target: “ftp://ftp.domain.ir”	object: priority: int weight: int target: string	URI

وزن‌دهی به رکوردها و زمان اعتبار رکورد

اگر چند رکورد مشابه (مثلا A) برای یک زیردامنه تعریف کرده‌اید، می‌توانید به هر کدام یک وزن اختصاص دهید تا بر اساس این وزن به کوئری کاربر پاسخ داده شود. برای این کار می‌توانید یک مقدار عددی برای فیلد weight هر رکورد تعیین کنید. وزن صفر به معنای غیرفعال بودن رکورد می‌باشد. اگر مقدار این فیلد تعیین نشود معادل 1 در نظر گرفته می‌شود. زمان اعتبار رکورد در فیلد ttl بر اساس ثانیه تعیین می‌شود.

Values	Type	Record Field
0-int64:MAX	int	weight
0-int64:MAX (Seconds)	int	ttl

موقعیت جغرافیایی

با استفاده از فیلد geo می‌توانید رکوردها را بر اساس موقعیت جغرافیایی کاربر تقسیم‌بندی کنید تا مثلا برای کاربران ایرانی (کشور) یا کاربران آسیایی (قاره) از رکوردهای متفاوتی استفاده کنید. همچنین با استفاده از فیلد blockedGeo می‌توانید رکوردها را بر اساس موقعیت جغرافیایی مستثنی کنید. دقت شود که می‌توان هر دو فیلد geo و blockedGeo را همزمان داشته باشیم ولی نمی‌توان دو موقعیت جغرافیایی کاملا یکسان را در هر دو ذخیره کرد. کد دو حرفی کشورها بر اساس استاندارد ISO 3166-1 تعیین می‌شود. برای دریافت کد قاره‌ها می‌توانید به این لینک مراجعه کنید.

Type	Record Field
[]object	geo
[]object	blockedGeo

Values	Type	GEO Field
Two-Letter code	string	continent
ISO 3166-1 alpha-2	string	country

فعالسازی Health Check

برای این کار فقط کافی‌ست فیلد hc را به یک رکورد اضافه کنید و مقدار enabled آن را true کنید. این ابزار در حال حاضر از سه protocol پشتیبانی می‌کند که عبارتند از tcp و http و https. اگر از پروتکل‌های http و https استفاده می‌کنید، می‌توانید مقدار path را نیز تعریف کنید تا healthcheck روی یک آدرس خاص انجام شود. در صورت استفاده از پروتکل https لازم است که مقدار host را بر اساس RFC952 تعیین کنید تا امکان handshake فراهم شود. با استفاده از فیلد port می‌توانید پورت مورد نظر برای انجام healthcheck را تعیین کنید. مقدار پورت باید بین 1 تا 65535 باشد.

Type	Record Field
object	hc

Values	Type	HC Field
true, false, yes, no	bool	enabled
http, https, tcp	string	protocol
1-65535	int	port
RFC 952	string	host
128 characters or less	string	path

نمونه تنظیمات برای اتصال به API Server ستون

فایل kubeconfig از لینک زیر در دسترس است:

➜ curl https://kise.roo.cloud/neda-kubeconfig/kubeconfig

دستورهای پر استفاده kubectl

اعمال فایل manifest: بعد از هر بار تغییر مقادیر فقط کافیست دستور زیر را در ترمینال وارد کنید تا تغییرات جدید اعمال شوند. همچنین برای ساخت اولین بار resource هم می‌توانید از همین دستور استفاده کنید.

➜ kubectl --context sotoon apply -f /path/to/manifest.yaml

نمایش همه resourceهای DomainZone:

➜ kubectl --context sotoon --namespace <your-namespace> get domainzones

نمایش یک DomainZone:

➜ kubectl --context sotoon --namespace <your-namespace> get \
          domainzones/<manifest-name> \
          -o yaml

دریافت مقدار NSDomain یک resource:

➜ kubectl --context sotoon --namespace <your-namespace> get \
          domainzones/<manifest-name> \
          -o jsonpath='{.spec.NSDomain}'

حذف یک resource: دقت کنید که این عمل غیر قابل بازگشت است.

➜ kubectl --context sotoon --namespace <your-namespace> delete \
          -f /path/to/manifest.yaml

مستندات

📄 راهنمای استفاده از API سرویس DNS