Skip to main content

Frequently Asked Questions (FAQ)

Here are answers to commonly asked questions when using the KIWI platform.

Getting Started​

Q. I'm using KIWI for the first time. How do I get started?​

A. Follow these steps to get started with KIWI:

  1. Register the server you want to manage on the [Device Management] page
  2. Connect a K8s cluster or Docker runtime on the [Runtime Environment] page
  3. Link a Git repository on the [Service Management] page
  4. Complete build and deployment configuration .

For more details: System Registration Scenario

Q. What permissions do I need?​

A. KIWI uses the following permission structure:

  • device: [Device Management] - Server/device management
  • infra: [Runtime Environment] - K8s/Docker environment management
  • service: [Service Management] - Service build/deployment
  • backup: [Backup Management] - Backup/restore operations
  • database: [Database Management] - Database management
  • audit: [Audit Log] - Log viewing

Request permissions from an administrator on the [Permission Management] page.

Device Management​

Q. Server connection test is failing.​

A. Please check the following:

  1. Network check: Verify that the server IP is accessible .
  2. SSH port check: If using a port other than the default (22), enter it correctly .
  3. Firewall check: Verify that the SSH port is allowed in the firewall
  4. Authentication check: Verify SSH username and password (or SSH private key)

Related page: [Device Management]

Q. How do I register a server that requires access through a gateway?​

A. KIWI supports multi-hop SSH:

  1. Register the gateway server first on the [Device Management] page
  2. When registering internal servers, select the gateway server as the parent device .
  3. Enter internal server information (private IP, port)

Runtime Environment​

Q. How do I connect an external Kubernetes cluster?​

A. Follow these steps:

  1. Go to the [Runtime Environment] page
  2. Click the "Import External Runtime" button .
  3. Upload kubeconfig file or enter it directly .
  4. Test the connection and save .

Note: kubeconfig must contain a valid token.

For more details: System Registration Scenario

Q. Docker runtime is not connecting.​

A. Please check the following:

  1. Docker daemon check: systemctl status docker
  2. Socket permission check: Verify that the user belongs to the docker group
  3. Remote API settings: If using TCP socket, check /etc/docker/daemon.json configuration .

Related page: [Runtime Environment]

Service Management​

Q. Git repository connection is failing.​

A. Please check the following:

  1. URL format: HTTPS URL is recommended (https://gitlab.com/...)
  2. Token permissions: Personal Access Token needs read_repository permission .
  3. Token expiration: Check token validity period

Related page: [Service Management]

Q. Build is failing. How do I check it?​

A. Follow these steps when a build fails:

  1. [Service Management] → Select service → Build tab
  2. Check the log of the failed build
  3. Common causes:
    • Dockerfile syntax error
    • Base image not accessible .
    • Dependency installation failure
    • Registry authentication failure

Q. Image push is failing.​

A. Please check the following:

  1. Registry URL: Verify the correct registry address .
  2. Authentication credentials: Check registry login information .
  3. Project permissions: Verify push permissions for the project in the registry .
  4. Image tag: Use the correct tag format

Related page: [Service Management]

Security Scanning​

Q. SAST scan results are not appearing.​

A. Please check the following:

  1. Supported languages: Verify that CodeQL/Semgrep supports the language
  2. Repository size: Large repositories may take longer to scan
  3. Source code location: Verify that source code is in the root directory .

Related page: [Service Management] → Security tab

For more details: Security Scan Setup Scenario

Q. Too many vulnerabilities appear in SCA scan.​

A. Use the VEX filter:

  1. [Service Management] → Select service → Security tab
  2. Enable "VEX Filter" in SCA results .
  3. Vulnerabilities that don't actually affect you will be automatically filtered .

You can also set exception policies to ignore specific vulnerabilities.

Q. How do I download SBOM?​

A. Follow these steps:

  1. [Service Management] → Select service → Security tab
  2. Click "Generate SBOM" button .
  3. Select source SBOM or image SBOM
  4. Download in CycloneDX or SPDX format

For more details: Security Scan Setup Scenario

Deployment​

Q. Pod does not start after deployment.​

A. Please check the following:

  1. Image pull: Verify that the image is pulled correctly .
  2. Resource limits: Check that CPU/memory limits are not too low
  3. Environment variables: Verify that required environment variables are set
  4. Port configuration: Verify that container port is configured correctly .

Debugging method:

kubectl describe pod <pod-name> -n <namespace>
kubectl logs <pod-name> -n <namespace>

Q. Cannot access the deployed service.​

A. Please check the following:

  1. Service configuration: Verify ClusterIP/LoadBalancer/NodePort
  2. Ingress configuration: Check Ingress rules and domain settings .
  3. Network policy: Verify that traffic is not blocked by NetworkPolicy

Backup Management​

Q. How do I create a backup?​

A. Follow these steps:

  1. Go to the [Backup Management] page
  2. Click "Create Backup" button .
  3. Select backup target (etcd, database, PVC, etc.)
  4. Select backup storage (local, MinIO, external storage)
  5. Execute backup

Q. How do I restore from a backup?​

A. Follow these steps:

  1. Go to the [Backup Management] page
  2. Select the backup to restore
  3. Click "Restore" button .
  4. Verify restore target and execute .

Warning: Restore will overwrite existing data. Proceed with caution.

Permissions and Users​

Q. How do I invite a new user?​

A. Manager permission or higher is required:

  1. Go to the [User Management] page
  2. Click "Invite User" button .
  3. Enter email and select role .
  4. Send invitation

Q. How do I change user permissions?​

A. Manager permission or higher is required:

  1. Go to the [Permission Management] page
  2. Select the user to change permissions .
  3. Check/uncheck required permissions .
  4. Save

Troubleshooting​

Q. Screen is stuck on loading.​

A. Try the following:

  1. Refresh browser (Ctrl+F5)
  2. Clear browser cache
  3. Try with a different browser .
  4. Check network connection .

If the problem persists, contact an administrator.

Q. An error message is displayed.​

A. Check the error message and refer to the following:

  • 401 Unauthorized: Login expired → Log in again
  • 403 Forbidden: Insufficient permissions → Request permissions from administrator
  • 404 Not Found: Resource not found → Check URL and resource existence .
  • 500 Internal Error: Server error → Contact administrator

Additional Help​

For more detailed information, refer to the following documentation:

System Configuration​

Build and Deployment​

Operations Management​

Administrator Functions​