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

کانتینری که درخواست شده را برای به‌روزرسانی محدودیت‌های منابع (CPU، حافظه، I/O و غیره) کوئری می‌کند.

---

🧩 دستور کلی

async updateContainerResources(containerId, options = {})

---

شرح عملکرد

این متد به شما امکان می‌دهد تا منابع کانتینر را بدون نیاز به ایجاد مجدد آن به‌روزرسانی کنید. می‌توانید محدودیت‌های CPU، حافظه، I/O و دیگر پارامترها را تغییر دهید.

مهم: این تغییرات بدون توقف کانتینر اعمال می‌شوند.

---

ورودی‌ها

پارامتر	نوع	اجباری	توضیح
containerId	String	بله	شناسه یا نام کانتینر برای به‌روزرسانی
options	Object	بله	گزینه‌های منابع برای تغییر
options.memory	String	خیر	محدودیت حافظه (مثل: 512m, 1GB)
options.memory-reservation	String	خیر	رزرو حافظه (soft limit)
options.memory-swap	String	خیر	کل استفاده حافظه (با swap)
options.cpu-share	Number	خیر	سهم CPU (۲-۲۶۲۱۴۴)
options.cpu-quota	Number	خیر	محدودیت CPU (microseconds)
options.cpu-period	Number	خیر	بازه CPU (microseconds، پیش‌فرض: ۱۰۰۰۰۰)
options.cpu-rt-runtime	Number	خیر	محدودیت CPU RT (microseconds)
options.cpu-rt-period	Number	خیر	بازه CPU RT (microseconds)
options.cpuset-cpus	String	خیر	CPU مورد استفاده (مثل: 0-2,4)
options.cpuset-mems	String	خیر	گره‌های حافظه (NUMA)
options.blkio-weight	Number	خیر	وزن I/O دیسک (۱۰-۱۰۰۰)
options.kernel-memory	String	خیر	محدودیت حافظه kernel
options.kernel-memory-tcp	String	خیر	محدودیت حافظه TCP kernel
options.pids-limit	Number	خیر	حداکثر تعداد processes
options.l3-cache-schema	String	خیر	تنظیمات Intel RDT/CAT L3
options.mem-bw-schema	String	خیر	تنظیمات Intel RDT/MBA
options.debug	Boolean	خیر	فعال کردن حالت debug

---

خروجی

نوع: String (پیام نتیجه عملیات)

خروجی:

Using debug verbosity
Loading container from config file: `/run/crun/111/config.json`

یا نتیجه معمولی از runtime.

---

استثناها (Errors)

ContainerNotFound (404)

پیام: "No container exists with the specified name or ID prefix."

زمان رخ دادن: کانتینری با شناسه/نام درخواستی یافت نشود

جزئیات:

{
  "type": "NOT_FOUND",
  "statusCode": 404,
  "containerId": "invalid-id"
}

راهنمای حل:

• شناسه کانتینر را بررسی کنید
• listContainers() استفاده کنید تا تمام کانتینرها را ببینید
• نام یا ID صحیح را وارد کنید

---

ResolveContainerName (500)

پیام: "Database error occurred while resolving container name or ID."

زمان رخ دادن: خطای دیتابیس در تطابق شناسه/نام کانتینر

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "input": "container-id",
  "error": "Database connection lost"
}

راهنمای حل:

• اتصال دیتابیس را بررسی کنید
• لاگ‌های دیتابیس را مطالعه کنید
• دیتابیس را راه‌اندازی کنید

---

FetchContainerState (500)

پیام: "Database error occurred while fetching container state."

زمان رخ دادن: خطای دیتابیس هنگام خواندن وضعیت کانتینر

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Query timeout"
}

راهنمای حل:

• دیتابیس را بررسی کنید
• اتصال را تأیید کنید

---

OptionConflict (422)

پیام: "Failed to validate update options."

زمان رخ دادن: گزینه‌های ورودی نامعتبر باشند یا هیچ گزینه معتبری ارائه نشود

جزئیات:

{
  "type": "VALIDATION_ERROR",
  "statusCode": 422,
  "error": "No valid options provided for update"
}

راهنمای حل:

• حداقل یک گزینه معتبر ارائه دهید
• نام‌های گزینه‌ها را بررسی کنید
• از فرمت kebab-case استفاده کنید

---

ApplyUpdatedResources (500)

پیام: "Failed to apply updated resources to container."

زمان رخ دادن: خطا در بروزرسانی منابع

جزئیات:

{
  "type": "DB_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Update failed"
}

راهنمای حل:

• منابع درخواستی را بررسی کنید
• مقادیر معتبر را استفاده کنید

---

UpdateMemoryContainerResources (500)

پیام: "Insufficient system memory."

زمان رخ دادن: حافظه سیستم برای تنظیم کردن محدودیت کافی نیست

جزئیات:

{
  "type": "CONTAINER_SERVICE_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Insufficient system memory"
}

راهنمای حل:

• محدودیت حافظه را کاهش دهید
• سیستم‌ها را بررسی کنید
• حافظه آزاد کنید

---

UpdateFailure (500)

پیام: "Failed to update container resources through ContainerManager."

زمان رخ دادن: خطا در به‌روزرسانی توسط container manager

جزئیات:

{
  "type": "CONTAINER_SERVICE_ERROR",
  "statusCode": 500,
  "containerId": "abc123def456",
  "error": "Runtime error"
}

راهنمای حل:

• سرویس K3 فعال است یا خیر؟
• لاگ‌های سرویس را مطالعه کنید
• cgroup سیستم را بررسی کنید

---

GenericFailure (500)

پیام: "Generic failure during update."

زمان رخ دادن: خطای نامشخص دیگر

جزئیات:

{
  "type": "GENERIC_ERROR",
  "statusCode": 500,
  "error": "Unknown error"
}

راهنمای حل:

• لاگ‌های کامل را بررسی کنید
• سرویس‌های K3 را دوباره شروع کنید

---

واحدهای منابع

منبع	واحد	مثال
memory	بایت (b, kb, mb, gb)	512m, 1GB
memory-reservation	بایت	256m, 512MB
memory-swap	بایت	2GB
cpu-share	عدد (2-262144)	1024, 2048
cpu-quota	microseconds	500000, 1000000
cpu-period	microseconds	100000, 500000
blkio-weight	عدد (10-1000)	100, 500
pids-limit	عدد	100, 500

---

مثال‌های استفاده

مثال 1: به‌روزرسانی محدودیت حافظه

const K3Core = require('k3-core');

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.updateContainerResources('my-container', {
      'memory': '512MB'
    });
    console.log('Memory limit updated to 512MB');
    console.log(result);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 2: به‌روزرسانی محدودیت CPU

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.updateContainerResources('app-container', {
      'cpu-quota': 500000,
      'cpu-period': 1000000
    });
    console.log('CPU limit updated (0.5 CPU)');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 3: به‌روزرسانی چند منبع

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.updateContainerResources('web-container', {
      'memory': '1GB',
      'memory-reservation': '512MB',
      'memory-swap': '2GB',
      'cpu-share': 1024
    });
    console.log('Multiple resources updated successfully');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 4: تنظیم CPU مخصوص

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.updateContainerResources('worker-container', {
      'cpuset-cpus': '0-2,4',
      'cpuset-mems': '0,1'
    });
    console.log('Container pinned to specific CPUs and NUMA nodes');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 5: به‌روزرسانی محدودیت processes

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.updateContainerResources('sandbox-container', {
      'pids-limit': 100
    });
    console.log('PID limit set to 100');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 6: به‌روزرسانی با debug mode

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.updateContainerResources('debug-container', {
      'memory': '1GB',
      'cpu-quota': 1000000,
      'debug': true
    });
    console.log('Debug output:');
    console.log(result);
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

مثال 7: به‌روزرسانی I/O weight

(async () => {
  const k3 = new K3Core();
  
  try {
    const result = await k3.containerCore.updateContainerResources('disk-intensive-container', {
      'blkio-weight': 500
    });
    console.log('I/O weight set to 500 (higher priority)');
  } catch (error) {
    console.log(error.createFullMessage());
  }
})();

---

الگوهای خطا و راهنمای حل

الگو 1: کانتینر یافت نشد

خطا: ContainerNotFound (404)

راهنمای حل:

try {
  await k3.containerCore.updateContainerResources('invalid-container', {
    'memory': '512m'
  });
} catch (error) {
  if (error.type === 'NOT_FOUND') {
    // Get list of all containers
    const allContainers = await k3.containerCore.listContainers({ all: true });
    console.log('Available containers:', allContainers.map(c => c.name));
    
    // Find and update the correct container
    const container = allContainers.find(c => c.name.includes('target'));
    if (container) {
      await k3.containerCore.updateContainerResources(container.id, {
        'memory': '512m'
      });
    }
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 2: حافظه ناکافی

خطا: UpdateMemoryContainerResources (500)

راهنمای حل:

try {
  await k3.containerCore.updateContainerResources('my-container', {
    'memory': '64GB'  // بیش از حد دستگاه
  });
} catch (error) {
  if (error.message.includes('Insufficient system memory')) {
    console.log('Requested memory exceeds available system memory');
    
    // Check available memory
    const inspect = await k3.containerCore.inspectContainer('my-container');
    const currentLimit = inspect.hostConfig?.resources?.memory?.limit;
    console.log(`Current memory limit: ${(currentLimit / 1024 / 1024).toFixed(2)}MB`);
    
    // Use reasonable limit
    await k3.containerCore.updateContainerResources('my-container', {
      'memory': '2GB'
    });
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 3: گزینه‌های نامعتبر

خطا: OptionConflict (422)

راهنمای حل:

const validOptions = {
  memory: 'رزرو حافظه (512m, 1GB)',
  'memory-reservation': 'soft limit حافظه',
  'memory-swap': 'کل حافظه با swap',
  'cpu-share': 'سهم CPU',
  'cpu-quota': 'محدودیت CPU',
  'cpu-period': 'بازه CPU',
  'blkio-weight': 'وزن I/O',
  'pids-limit': 'حد max processes'
};

try {
  await k3.containerCore.updateContainerResources('my-container', {
    'invalid-option': 'value'  // اشتباه
  });
} catch (error) {
  if (error.type === 'VALIDATION_ERROR') {
    console.log('Valid update options:');
    Object.entries(validOptions).forEach(([key, desc]) => {
      console.log(`  ${key}: ${desc}`);
    });
  } else {
    console.log(error.createFullMessage());
  }
}

الگو 4: به‌روزرسانی محتاط منابع

راهنمای حل:

const safeUpdateResources = async (containerId, newResources) => {
  try {
    // Get current resources first
    const inspect = await k3.containerCore.inspectContainer(containerId);
    if (!inspect) {
      console.log('Container not found');
      return;
    }
    
    const currentMem = inspect.hostConfig?.resources?.memory?.limit;
    const newMem = newResources.memory;
    
    console.log(`Current memory: ${(currentMem / 1024 / 1024).toFixed(2)}MB`);
    console.log(`Requested memory: ${newMem}`);
    
    // Warn if decreasing resources
    if (newMem && currentMem && newMem < currentMem) {
      console.log('⚠️  Warning: Decreasing memory limit');
    }
    
    // Apply update
    const result = await k3.containerCore.updateContainerResources(
      containerId,
      newResources
    );
    console.log('Update successful');
    return result;
    
  } catch (error) {
    console.log(error.createFullMessage());
    throw error;
  }
};

await safeUpdateResources('my-container', { 'memory': '1GB' });

---

نکات عملی

1. واحدهای حافظه:

   • b, kb, mb, gb استفاده کنید
   • مثال: '512m', '1GB', '256MB'

2. CPU Quota و Period:

   • cpu-quota: مدت زمان مجاز (microseconds)
   • cpu-period: بازه زمانی (پیش‌فرض: 100000)
   • مثال: quota=500000, period=1000000 = 0.5 CPU

3. CPU Share:

   • برای تقسیم CPU بین کانتینرها
   • مقدار بالاتر = اولویت بیشتر
   • پیش‌فرض: 1024

4. NUMA Aware:

   • cpuset-mems برای انتخاب گره‌های حافظه
   • مفید برای سیستم‌های NUMA

5. بهترین شیوه:

   • ابتدا وضعیت فعلی بررسی کنید
   • تغییرات کم و مشخص اعمال کنید
   • بعد از تغییر اثر آن را بررسی کنید

---

مرجع سریع

وضعیت	کد	توضیح
موفق	200	منابع به‌روزرسانی شدند
یافت نشد	404	ContainerNotFound
گزینه نامعتبر	422	OptionConflict
حافظه ناکافی	500	UpdateMemoryContainerResources
خطای اعمال	500	ApplyUpdatedResources
خطای عمومی	500	GenericFailure

---

نسخه: 1.3
تاریخ آپدیت: 9 آذرماه ۱۴۰۴
تیم توسعه: K3 Development Team