ফেজ ৫ — API ও ইন্টিগ্রেশন#

৯টি লেসন · লেভেল: মধ্যম থেকে উন্নত

প্যানেলে যা যা করা যায়, প্রায় সবই API দিয়ে করা যায়। বিলিং সিস্টেম, নিজের অ্যাপ বা অটোমেশন স্ক্রিপ্ট — সব এখান থেকেই VirtFusion-এর সাথে কথা বলে।

এই ফেজের পাথগুলো বাস্তব ইন্টিগ্রেশনে যাচাই করা। তবে প্রতিটি এন্ডপয়েন্টের পূর্ণ রিকোয়েস্ট ফিল্ড ও রেসপন্স কাঠামো আপনার প্যানেলের সংস্করণ অনুযায়ী বদলায় — নিজের কন্ট্রোল সার্ভারের API রেফারেন্স মিলিয়ে নিন।

এই ফেজে কী আছে#

লেসন ১ — টোকেন, বেস URL ও অনুরোধের গঠন#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: টোকেনই পুরো প্যানেল। যার হাতে টোকেন, সে আপনার সব কাজ করতে পারে। তাই Access ঘরে নিজের অ্যাপ্লিকেশনের IP বসিয়ে আটকে দিন, git-এ রাখবেন না, লগেও লিখবেন না। তারপর এরর কোডগুলো কী বলছে সেটা শিখুন।

টোকেন তৈরি#

প্যানেলে System → API → Create Token। টোকেনকে নির্দিষ্ট IP-তে সীমাবদ্ধ করা যায় — প্রোডাকশনে অবশ্যই করবেন।

নিরাপত্তা: টোকেন পেলে যে কেউ পুরো প্যানেল চালাতে পারবে। এটি গিটে রাখবেন না, লগে লিখবেন না। আপনার অ্যাপের আউটবাউন্ড IP স্থির রাখুন, তারপর টোকেন সেই IP-তে লক করুন।

অনুরোধের গঠন#

POST /api/v1/servers HTTP/1.1
Host: panel.example.com
Authorization: Bearer <API_TOKEN>
Content-Type: application/json
Accept: application/json

এরর সামলানো#

৭.x সংস্করণে প্রতি-ইউজার রেট লিমিট বসানো যায়, তাই ক্লায়েন্টে exponential backoff রাখুন। টাইমআউট ১৫ সেকেন্ডের মতো যুক্তিসংগত, কারণ কিছু কল হাইপারভাইজার পর্যন্ত যায়।

লেসন ২ — ইউজার ও SSO টোকেন#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: VirtFusion ইউজারে নিজের কাস্টমার id বসিয়ে দিন extRelationId দিয়ে, তাহলে পরে সবসময় খুঁজে পাবেন। SSO হলো বাকি অর্ধেক — লগইন করা কাস্টমারকে দ্বিতীয়বার পাসওয়ার্ড ছাড়াই প্যানেলে ঢুকিয়ে দেয়।

ইউজার তৈরি ও খোঁজা#

POST /api/v1/users
GET  /api/v1/users/{extRelationId}/byExtRelation

byExtRelation দিয়ে নিজের সিস্টেমের ইউজার আইডি ধরে VirtFusion ইউজার খুঁজে পাওয়া যায়। নিজের ডাটাবেসে VirtFusion-এর ভেতরের আইডি প্রাইমারি কী করবেন না।

SSO — কাস্টমারকে প্যানেলে ঢোকানো#

কাস্টমার আপনার সাইটে লগইন করা অবস্থায় "Open console" চাপলে তাকে পাসওয়ার্ড ছাড়াই VirtFusion-এ ঢোকানো যায়:

POST /api/v1/users/{userId}/authenticationTokens
POST /api/v1/users/{userId}/serverAuthenticationTokens/{serverId}

• প্রথমটি প্যানেলে সাধারণ লগইনের টোকেন দেয়
• দ্বিতীয়টি সরাসরি নির্দিষ্ট সার্ভারের পাতায় নিয়ে যায়

টোকেন স্বল্পস্থায়ী — তৈরি করেই সাথে সাথে রিডাইরেক্ট করুন, সংরক্ষণ করবেন না।

সতর্কতা: SSO টোকেন অ্যাডমিন অ্যাকাউন্টের জন্য নয়। কাস্টমারের ইউজার আইডি ব্যবহার করুন, নইলে "Oops! Something went wrong" আসবে।

লেসন ৩ — সার্ভার তৈরি ও বিল্ড#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: দুইটা কল, একটা নয়। POST /servers রিসোর্স আর IP আটকায়। POST /servers/{id}/build OS বসায়। আর বিল্ড সাথে সাথে শেষ হয় না — কিউ পোল করে নিশ্চিত হোন, তারপর কাস্টমারকে তথ্য পাঠান।

দুই ধাপের প্রবাহ#

POST /api/v1/servers          → সার্ভার রেকর্ড, রিসোর্স ও IP বরাদ্দ
POST /api/v1/servers/{id}/build → OS বসে, cloud-init চলে, VM চালু হয়

তৈরির সময় সাধারণত যা পাঠাতে হয়: হাইপারভাইজার গ্রুপ আইডি, প্যাকেজ আইডি, ইউজার আইডি, IPv4 সংখ্যা। বিল্ডের সময়: টেমপ্লেট আইডি, হোস্টনেম, পাসওয়ার্ড বা SSH কী।

কিউ পোলিং#

ভারী কাজগুলো সিঙ্ক্রোনাস নয় — একটি job আইডি ফেরত আসে:

GET /api/v1/queue/{jobId}

নকশার নিয়ম: বিল্ড শেষ হয়েছে ধরে নেবেন না। কিউ পোল করুন, অথবা সার্ভারের অবস্থা (GET /servers/{id}) দেখে নিশ্চিত হোন যে state ঠিক আছে এবং IPv4 বসেছে।

একটি বাস্তব ক্রম#

1. কাস্টমার অর্ডার করল
2. byExtRelation দিয়ে ইউজার খুঁজুন, না থাকলে POST /users
3. POST /servers — সার্ভার তৈরি
4. POST /servers/{id}/build — OS বসানো
5. GET /queue/{jobId} পোল করুন
6. state = ready এবং IPv4 আছে → কাস্টমারকে তথ্য পাঠান

লেসন ৪ — সার্ভার নিয়ন্ত্রণ ও পরিবর্তন#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: এটাই রিমোট কন্ট্রোল। পাওয়ার, রিসাইজ, IP, পাসওয়ার্ড রিসেট। একটা জিনিস খেয়াল রাখবেন — রিসাইজে প্রতিটা জিনিসের জন্য আলাদা কল লাগে। এক অনুরোধে CPU আর RAM একসাথে বদলানো যায় না।

পাওয়ার#

POST /api/v1/servers/{id}/power/{action}

{action}: boot, shutdown, restart, poweroff (আপনার সংস্করণের রেফারেন্স মিলিয়ে নিন)।

রিসোর্স বদল#

POST /api/v1/servers/{id}/modify/cpuCores
POST /api/v1/servers/{id}/modify/memory
POST /api/v1/servers/{id}/modify/cpuThrottle
POST /api/v1/servers/{id}/modify/traffic

আপগ্রেড/ডাউনগ্রেডে প্রতিটি আলাদা কল — একসাথে সব পাঠানোর চেষ্টা করবেন না।

IP ব্যবস্থাপনা#

GET    /api/v1/servers/{id}/ipv4        # বর্তমান IP তালিকা
POST   /api/v1/servers/{id}/ipv4Qty     # কতটি IPv4 থাকবে, বাড়ানো/কমানো

অন্যান্য#

সতর্কতা: ডিলিট অপরিবর্তনীয় — ডিস্ক ও IP ফেরত চলে যায়। নিজের অ্যাপে দুই ধাপের নিশ্চিতকরণ রাখুন, আর গুরুত্বপূর্ণ সার্ভারে vfcli-ctrl server:dnd enable ব্যবহার করুন।

লেসন ৫ — ইনভেন্টরি: হাইপারভাইজার, প্যাকেজ, IP#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: কারও টাকা নেওয়ার আগে প্যানেলকে জিজ্ঞেস করুন জায়গা কত বাকি। গ্রুপ ভরা থাকলে টাকা তো নিয়ে ফেলেছেন, আর বিল্ড ব্যর্থ হবে। vCPU ৩:১ বা ৪:১ ওভারকমিট করুন, RAM ১:১ রাখুন, আর প্রতিটা নোডের ১০ থেকে ১৫ শতাংশ খালি রাখুন।

এন্ডপয়েন্ট#

GET /api/v1/compute/hypervisors
GET /api/v1/compute/hypervisors/groups
GET /api/v1/compute/hypervisors/groups/{groupId}/resources
GET /api/v1/packages
GET /api/v1/connectivity/ipblocks

ক্যাপাসিটি যাচাই — বিক্রির আগে#

groups/{id}/resources দিয়ে জানা যায় ওই গ্রুপে আর কত জায়গা আছে। অর্ডার নেওয়ার আগেই এটি দেখে নেওয়া ভালো, নইলে টাকা নিয়ে বিল্ড ব্যর্থ হবে।

বাস্তব নকশায় দুইটি সুরক্ষা রাখুন:

1. ওভারকমিট অনুপাত — vCPU-তে ৩:১ বা ৪:১ চললেও RAM-এ সাধারণত ১:১
2. রিজার্ভড হেডরুম — নোডের ১০–১৫% ফাঁকা রাখুন, রিবুট ও মাইগ্রেশনের জন্য

একাধিক অঞ্চল#

একাধিক লোকেশন থাকলে প্রতি অঞ্চলে আলাদা কন্ট্রোল সার্ভার হতে পারে। তখন নিজের অ্যাপে প্রতি অঞ্চলের জন্য আলাদা বেস URL ও টোকেন রাখুন, এবং সার্ভার কোন প্যানেলের — সেটি ডাটাবেসে লিখে রাখুন। ভুল প্যানেলে জিজ্ঞাসা করলে "not found" আসবে।

লেসন ৬ — SSH কী ব্যবস্থাপনা#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: বিল্ডের আগেই কাস্টমারের পাবলিক কী বসিয়ে রাখুন, তাহলে VM-এর ভেতরে নিজে থেকেই ঢুকে যাবে। তখন আর কাউকে ইমেইলে রুট পাসওয়ার্ড পাঠাতে হয় না — মূল উদ্দেশ্যটা ওটাই।

GET    /api/v1/ssh_keys
POST   /api/v1/ssh_keys
GET    /api/v1/ssh_keys/user/{userId}
DELETE /api/v1/ssh_keys/{keyId}

কাস্টমারের কী আগে থেকে বসিয়ে রাখলে বিল্ডের সময় সেটি VM-এ চলে যায় — পাসওয়ার্ড ইমেইলে পাঠানোর দরকার পড়ে না। এটিই নিরাপদ অভ্যাস।

লেসন ৭ — Webhook ও Event Hook#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: আপনি VirtFusion-কে জিজ্ঞেস করার বদলে ও নিজেই আপনাকে জানায়। দুইটা নিয়ম না মানলে ভুগবেন — দ্রুত 200 ফেরত দিন আর আসল কাজ নিজের কিউতে করুন, আর এন্ডপয়েন্ট idempotent রাখুন, কারণ একই ইভেন্ট একদিন দুইবার আসবেই।

Webhook#

VirtFusion কোনো ঘটনা ঘটলে আপনার URL-এ HTTP POST পাঠায়।

পেলোড JSON — মূল তথ্য থাকে data-তে, সাথে event, hookId, eventStatus ও কন্ট্রোল ডোমেইনের তথ্য।

অথেন্টিকেশন: ঐচ্ছিক bearer টোকেন সমর্থিত; টোকেন সবসময় base64 এনকোড হয়ে Authorization হেডারে যায়।

ঘটনার সংখ্যা: ৩৫টির বেশি, চার ভাগে —

নকশার নিয়ম#

• এন্ডপয়েন্ট আইডেমপোটেন্ট রাখুন — একই ঘটনা দুইবার এলেও ক্ষতি না হয়
• দ্রুত 200 ফেরত দিন, ভারী কাজ নিজের কিউতে ফেলুন
• টোকেন যাচাই করুন, নাহলে যে কেউ ভুয়া ইভেন্ট পাঠাতে পারবে

Slack, Discord, Google Chat, Pushover ও Telegram-এ পাঠানোর জন্য VirtFusion-এর webhook proxy অ্যাপ আছে।

Event Hook#

Webhook বাইরে বার্তা পাঠায়; event hook ঘটনার সময় নিজস্ব কোড/অ্যাকশন চালায় (হাইপারভাইজার-স্তরের হুকসহ)। যেখানে বাইরের সিস্টেমকে জানানো নয়, বরং ভেতরে কিছু করাতে হবে — সেখানে এটি ব্যবহার করুন।

লেসন ৮ — বিলিং ইন্টিগ্রেশন#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: WHMCS, Blesta, Clientexec বা এদের কোনোটা ব্যবহার করলে মডিউল কেউ আগেই লিখে রেখেছে। ওগুলো create, suspend, unsuspend, terminate করে। সার্ভার এন্ট্রির password ঘরে API টোকেন বসাতে হয় — এই জিনিসটা কেউ আন্দাজ করতে পারে না।

কোনটি কী#

প্রায় সব মডিউলই চারটি কাজ করে: create, suspend, unsuspend, terminate।

WHMCS সেটআপ — ধাপে ধাপে#

1. মডিউল নামিয়ে WHMCS-এর রুটে extract করুন (২.৫ সংস্করণে VirtFusion v6.0+ লাগে)
2. VirtFusion-এ System → API → Create Token — চাইলে IP-তে সীমাবদ্ধ করুন
3. WHMCS-এ Servers → Add — মডিউল "VirtFusion Direct Provisioning",

টোকেনটি password ঘরে বসান

1. সার্ভার গ্রুপ ও প্রোডাক্ট গ্রুপ বানান
2. প্রোডাক্টে Hypervisor Group ID ও Package ID বসান (VirtFusion থেকে নেওয়া)

কনফিগারেবল অপশন#

প্যাকেজের ডিফল্ট ওভাররাইড করা যায় — IPv4 সংখ্যা, স্টোরেজ, মেমরি, ব্যান্ডউইথ, CPU কোর, নেটওয়ার্ক ও স্টোরেজ প্রোফাইল। নাম হুবহু মিলতে হবে, নয়তো ConfigOptionMapping.php-এ ম্যাপ করে দিতে হবে।

একাধিক WHMCS#

একই কন্ট্রোল সার্ভারে একাধিক WHMCS চললে MultiInstance.php চালু করে প্রতিটির জন্য ১–৫ অক্ষরের আলাদা প্রিফিক্স দিন — নইলে ক্লায়েন্ট আইডি সংঘর্ষ করবে।

লেসন ৯ — নিজের প্যানেল বা অটোমেশন বানানো#

ভাই, জিনিসটা কী? আসলে ব্যাপারটা হলো: অনেক প্রোভাইডার VirtFusion-কে ইঞ্জিন হিসেবে রেখে সামনে নিজের ব্র্যান্ড বসায়। তবে কনসোল আর ব্যাকআপ UI আবার বানাতে যাবেন না — ওগুলোর জন্য SSO দিয়ে কাস্টমারকে পাঠিয়ে দিন। একটা পাতলা ক্লায়েন্ট লেয়ার রাখুন, যাতে বাকি কোড VirtFusion-এর ফিল্ডের নাম কখনো না শেখে।

কেন নিজের স্তর#

অনেক প্রোভাইডার VirtFusion-কে ইঞ্জিন হিসেবে রেখে নিজের UI বানায় — নিজের ব্র্যান্ড, নিজের চেকআউট, নিজের ভাষা।

হাইব্রিড নকশা — সবচেয়ে বাস্তবসম্মত#

সবকিছু নিজে বানানোর চেষ্টা করলে কনসোল ও ব্যাকআপের UI নকল করতে গিয়ে সময় নষ্ট হবে।

কোড সাজানোর নিয়ম#

একটি পাতলা ক্লায়েন্ট স্তর রাখুন, যেখানে থাকবে: retry, backoff, এরর ম্যাপিং, আর লগে টোকেন গোপন রাখা। বাকি অ্যাপ যেন VirtFusion-এর মাঠের নাম না জানে — তাহলে পরে অন্য ব্যাকএন্ড (যেমন Proxmox) যোগ করা সহজ হয়।

আপনার অ্যাপ
   │  ServerProvider (ইন্টারফেস)
   ▼
VirtFusionDriver ──▶ VirtFusionClient ──▶ /api/v1
                          │
                    retry / backoff / redacted log

যে ভুলগুলো সবচেয়ে বেশি হয়#

1. বিল্ড সিঙ্ক্রোনাস ধরে নেওয়া — কিউ পোল করুন
2. VirtFusion-এর ইউজার আইডি প্রাইমারি কী করা — extRelationId ব্যবহার করুন
3. রেট লিমিট উপেক্ষা — 429 হ্যান্ডল করুন
4. টোকেন IP-তে লক না করা — টোকেন ফাঁস হলে পুরো প্যানেল খোলা
5. ক্যাপাসিটি না দেখে অর্ডার নেওয়া — বিল্ড ব্যর্থ হবে, রিফান্ড দিতে হবে

ফেজ ৫ শেষে আপনি যা পারবেন#

• টোকেন বানিয়ে নিরাপদে API কল করা
• ইউজার ম্যাপিং ও SSO লগইন বসানো
• সার্ভার তৈরি → বিল্ড → কিউ পোলিং প্রবাহ লেখা
• পাওয়ার, রিসাইজ, IP ও পাসওয়ার্ড API চালানো
• ক্যাপাসিটি দেখে অর্ডার গ্রহণ করা
• webhook গ্রহণ ও যাচাই করা
• WHMCS বা নিজের প্যানেল যুক্ত করা

পরবর্তী: ফেজ ৬ — কাস্টমার প্যানেল